troubleshooting

This guide helps you identify and resolve common issues that may arise when working with the Instinct API. Use this as a reference when you encounter problems with API requests, data processing, or hardware interaction.

general api issues

connection issues

Problem: Unable to connect to the API

Possible causes:

• API service is not running
• Network connectivity issues
• Incorrect base URL

Solutions:

1. Verify that the service is running:

   # Check API health
   curl http://localhost:42069/system/healthz

2. Check network connectivity:

   ping localhost

3. Verify you're using the correct port (42069) and protocol (http)

authentication issues

Problem: Authentication failures

Possible causes:

• Headset not authenticated through companion app

Solutions:

1. Ensure the headset has been authenticated using the Nexstem companion app
2. IMPORTANT: The Nexstem companion app is the only authentication method available for Nexstem headsets. API Keys, Session-Based Authentication, and OAuth are not applicable.
3. If you have access to a display and keyboard, plug them through the USB Type C Port, and open the Authenticator application.
4. Check if the services are running.

request format issues

Problem: API returns 400 Bad Request

Possible causes:

• Invalid JSON format
• Missing required fields
• Invalid parameter values

Solutions:

1. Validate your JSON with a JSON linter
2. Check the API documentation for required fields
3. Ensure parameter values are within expected ranges

Example of proper request formatting:

curl -X POST http://localhost:42069/stream/streams \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "source",
        "executable": "data-generator",
        "config": {
          "frequency": 1
        }
      }
    ],
    "pipes": []
  }'

data processing issues

stream creation issues

Problem: Cannot create stream

Possible causes:

• Invalid stream configuration
• Duplicate node or pipe IDs
• Invalid executable references
• Cycle detected in the DAG

Solutions:

1. Verify that all node and pipe IDs are unique
2. Check that all referenced executables exist
3. Ensure the DAG structure has no cycles
4. Validate the configuration against the schema

stream execution issues

Problem: Stream stops unexpectedly

Possible causes:

• Node executables crashing
• Memory or resource limitations
• Unhandled exceptions in processing logic

Solutions:

1. Check node logs for error messages
2. Monitor system resources during execution
3. Ensure nodes handle errors properly
4. Add proper error handling in your node configurations

data flow issues

Problem: Data not flowing through the pipeline

Possible causes:

• Disconnected pipes
• Misconfigured nodes
• Data format mismatches between nodes

Solutions:

1. Verify that pipes connect nodes correctly
2. Check node configurations match expected input/output formats
3. Add logging nodes to debug data flow
4. Ensure source nodes are generating data

hardware issues

headset connection issues

Problem: Cannot connect to the EEG headset

Possible causes:

• Headset is powered off
• Headset is not connected to the same wifi network as your PC/Laptop.

Solutions:

1. Ensure the headset is powered on
2. Use the companion app to connect the headset to the same network as your are in.

eeg streaming issues

Problem: Cannot start EEG streaming

Possible causes:

• Impedance check is active
• Previous stream not properly terminated

Solutions:

1. Stop any active impedance checks
2. Verify stream configuration is valid
3. Check hardware status

signal quality issues

Problem: Noisy EEG signal

• High impedance on one or more electrodes
• Environmental electrical interference
• Subject movement or muscle artifacts
• Loose electrode connections

Solution:

1. Check impedance values for all electrodes
2. Ensure proper electrode placement and contact
3. Reduce environmental electrical interference
4. Ask the subject to remain still and relaxed
5. Apply appropriate filtering to the signal

Problem: Signal drift

• Electrode polarization
• Temperature changes
• Subject sweating
• Poor electrode contact

Solution:

1. Use higher quality electrodes or add fresh gel
2. Apply a high-pass filter (typically > 0.1 Hz)
3. Maintain consistent room temperature
4. Check and improve electrode-scalp contact

battery and power issues

Problem: Headset battery drains quickly

• High sampling rate configuration
• All electrodes active when not needed
• Wireless streaming at maximum data rate
• Old or degraded battery

Solution:

1. Lower sampling rate if appropriate for your application
2. Disable unused electrodes
3. Consider using wired connection when possible
4. Check battery health and replace if necessary

connectivity issues

Problem: Cannot connect to websocket stream

• API server not running
• Incorrect websocket URL
• Firewall blocking connection
• Network configuration issues

Solution:

1. Ensure the API server is running (GET /system/healthz)
2. Verify the websocket URL format
3. Check for firewall or network restrictions
4. Try connecting from the same machine first

Problem: Connection drops frequently

• Unstable network
• High data rate overwhelming connection
• Server resource limitations
• Distance from wireless access point

Solution:

1. Improve network stability
2. Reduce data rate (lower sampling rate or fewer channels)
3. Ensure server has sufficient resources
4. Move closer to wireless access point

file and storage issues

Problem: Insufficient storage space

• Disk space nearly full
• Long recording sessions
• High sampling rate generating large files
• Old temporary files not cleaned up

Solution:

1. Check available disk space
2. Archive or remove old files
3. Adjust recording parameters if appropriate
4. Clean up temporary files

performance issues

stream processing performance

Problem: High latency in data processing

Possible causes:

• Inefficient node implementations
• Insufficient hardware resources
• Buffer overflows
• Complex processing logic

Solutions:

1. Optimize node configurations
2. Adjust buffer sizes
3. Simplify processing logic
4. Monitor CPU and memory usage
5. Consider distributing processing across multiple streams

memory leaks

Problem: Increasing memory usage over time

Possible causes:

• Memory leaks in node executables
• Unbounded buffers
• Resources not being released

Solutions:

1. Implement proper resource cleanup
2. Set reasonable buffer limits
3. Restart services periodically
4. Monitor memory usage trends

advanced troubleshooting

logging and diagnostics

Enhance logging for better diagnostics:

1. Enable debug logging:

   curl -X POST http://localhost:42069/system/config \
     -H "Content-Type: application/json" \
     -d '{
       "logging": {
         "level": "debug",
         "includeTimestamp": true
       }
     }'

2. Use the debug command endpoint for advanced diagnostics:

   curl -X POST http://localhost:42069/system/debug/command \
     -H "Content-Type: application/json" \
     -d '{
       "command": "diagnostics",
       "level": "full"
     }'

recovery procedures

If the API becomes unresponsive:

1. Restart the service:

   # For systemd-based systems
   sudo systemctl restart instinct-api-service

2. Clear temporary data if necessary:

   # Location depends on your installation
   sudo rm -rf /var/lib/instinct/tmp/*

3. Verify services are running:

   systemctl status instinct*

getting help

If you're unable to resolve an issue using this guide:

1. Check the product documentation for updated information here
2. Contact support with the following information:
   • Detailed description of the issue
   • Steps to reproduce
   • API responses including error codes
   • System information
   • Logs if available

for additional help

If you continue to experience issues:

1. Check our API Reference for detailed endpoint documentation
2. Review the Basic Pipeline tutorial
3. Contact our support team for assistance