Troubleshooting

This guide covers common issues you may encounter when using Superserve and how to resolve them.

Authentication Issues

Error: Not authenticated. Run `superserve login` first.

Symptoms:

Browser doesn’t open
Device code doesn’t work
“Authorization pending” never completes

Solutions:

Check your internet connection
Try logging in again:
```
superserve logout
superserve login
```
Manually open the verification URL if the browser doesn’t open automatically:
```
Visit: https://console.superserve.ai/device?code=ABCD-EFGH
```
Check for firewall/proxy issues that may block access to api.superserve.ai

Deployment Issues

Error: 'name' is required in superserve.yaml

Cause: Missing name field in superserve.yaml.Solution:Add the name field:

superserve.yaml

name: my-agent
command: python agent.py

Error: Invalid agent name

Cause: Agent name doesn’t follow naming rules.Rules:

Must start with a lowercase letter
Can only contain lowercase letters, numbers, and hyphens
No special characters or spaces

Solution:

# ❌ Invalid
name: My-Agent
name: 123-agent
name: agent_name

# ✅ Valid
name: my-agent
name: agent-123
name: customer-support

Deployment stuck on 'Installing dependencies...'

Cause: Dependency installation is taking longer than expected or has failed.Solutions:

Wait up to 5 minutes for complex dependency installations
Check agent status:
```
superserve agents get my-agent
```

If status is FAILED, check the error message and fix your dependencies:

# Fix requirements.txt or package.json
# Then redeploy
superserve deploy

Error: Dependency install failed

Common causes:

Invalid package names in requirements.txt or package.json
Incompatible package versions
Package not available in PyPI or npm

Solutions:

Check the error message:
```
superserve agents get my-agent
```
Look for the Deps Error field.
Verify package names and versions in your dependency file:
requirements.txt
```
# ❌ Wrong
antrhopic

# ✅ Correct
anthropic
```
Test locally before deploying:
```
pip install -r requirements.txt
```
Redeploy after fixing:
```
superserve deploy
```

Error: Entrypoint file not found

Cause: The file specified in zero-config deploy doesn’t exist.Solution:Verify the file exists:

# ❌ Wrong
superserve deploy aget.py  # typo

# ✅ Correct
superserve deploy agent.py

Or use the full path:

superserve deploy src/agent.py

Secret Management Issues

Error: Missing required secret(s)

Cause: Agent requires secrets that haven’t been set.Solution:Set the required secrets:

superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...

Check which secrets are required:

superserve agents get my-agent

Look for the “Required Secrets” section.

Secret not available in agent runtime

Symptoms:

KeyError: 'ANTHROPIC_API_KEY' in Python
undefined in JavaScript/TypeScript

Solutions:

Verify the secret is set:
```
superserve secrets list my-agent
```

Check the key name matches exactly (case-sensitive):

# ❌ Wrong
api_key = os.environ["anthropic_api_key"]

# ✅ Correct
api_key = os.environ["ANTHROPIC_API_KEY"]

Set the secret if missing:

superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...

Error: Invalid format. Use KEY=VALUE

Cause: Secret command is missing the = separator.Solution:

# ❌ Wrong
superserve secrets set my-agent ANTHROPIC_API_KEY sk-ant-...

# ✅ Correct
superserve secrets set my-agent ANTHROPIC_API_KEY=sk-ant-...

Session Issues

Error: No session found matching 'abc123'

Cause: Session doesn’t exist or has been deleted.Solutions:

List available sessions:
```
superserve sessions list
```
Check if the session timed out (shows as status TIMEOUT)
Start a new session:
```
superserve run my-agent
```

Error: Ambiguous ID

Cause: The session ID prefix matches multiple sessions.Example:

Error: Ambiguous ID 'a1' — matches: a1b2c3d4e5f6, a1f9e8d7c6b5

Solution:Provide more characters:

# ❌ Ambiguous
superserve sessions resume a1

# ✅ Unique
superserve sessions resume a1b2

Session ended unexpectedly (TIMEOUT status)

Cause: Session was idle for more than 29 minutes.What happens:

Session status changes to TIMEOUT
Workspace files are destroyed
Cannot resume the session

Solution:Start a new session:

superserve run my-agent

Prevention:For long-running tasks, send periodic messages to keep the session active.

Cannot resume session (status 'ended')

Cause: The session was explicitly ended or timed out.Solution:You cannot resume ended sessions. Start a new one:

superserve run my-agent

Runtime Issues

Agent not responding

Diagnostic steps:

Check agent status:
```
superserve agents get my-agent
```
Ensure status is READY.
Check required secrets are set:
```
superserve agents get my-agent
```
Look for “Required Secrets” vs “Configured Secrets”.

Try a simple test:

superserve run my-agent "Hello" --single

Check session status:

superserve sessions list --agent my-agent

Agent responds slowly

Common causes:

Large dependencies still loading
Complex prompt or long conversation history
Network latency

Solutions:

Check deployment status:
```
superserve agents get my-agent
```
If status is DEPLOYING, wait for it to become READY.
Start a fresh session to reduce context size:
```
superserve run my-agent
```
Use simpler prompts for testing.

Import errors in agent code

Symptoms:

ModuleNotFoundError: No module named 'anthropic'

Causes:

Missing dependency in requirements.txt or package.json
Dependency install failed

Solutions:

Add the missing package:
requirements.txt
```
anthropic
```
Redeploy:
```
superserve deploy
```
Verify dependency installation:
```
superserve agents get my-agent
```

Configuration Issues

Error: Invalid YAML in superserve.yaml

Cause: Syntax error in YAML file.Common mistakes:

# ❌ Wrong (missing space after colon)
name:my-agent

# ✅ Correct
name: my-agent

# ❌ Wrong (inconsistent indentation)
secrets:
  - ANTHROPIC_API_KEY
   - DATABASE_URL

# ✅ Correct (consistent indentation)
secrets:
  - ANTHROPIC_API_KEY
  - DATABASE_URL

Solution:Validate your YAML with an online validator or:

python -c "import yaml; yaml.safe_load(open('superserve.yaml'))"

Ignore patterns not working

Cause: Ignore pattern doesn’t match the file structure.How ignore works:Patterns match against relative paths from project root:

ignore:
  - .venv              # Matches .venv/ directory
  - tests              # Matches tests/ directory
  - data/cache         # Matches data/cache/ directory

Note: These are always ignored automatically:

__pycache__, .git, node_modules, .venv, venv
Files starting with .env

Network and Connection Issues

Error: Cannot connect to Superserve API

Cause: Network connection issue or API is down.Solutions:

Check your internet connection
Verify API access:
```
curl https://api.superserve.ai/health
```
Check firewall/proxy settings that may block:
- api.superserve.ai
- console.superserve.ai
Try again - may be a temporary network issue

Error: Request timed out

Cause: Request took longer than 30 seconds.Common scenarios:

Large file upload during deploy
Slow network connection
API temporarily overloaded

Solutions:

Reduce deployment size with ignore patterns:
```
ignore:
  - tests
  - docs
  - data
```
Try again - may succeed on retry
Check network connection speed

Best Practices to Avoid Issues

Before deploying:

Test your agent locally
Verify all dependencies install correctly
Check superserve.yaml syntax
Use .env.example to document required secrets
Test with a simple prompt first

Regular maintenance:

Clean up old sessions: superserve sessions list --status timeout
Monitor deployment status after updates
Rotate secrets periodically
Keep dependencies up to date
Remove unused agents to reduce clutter

Getting Help

If you’re still experiencing issues:

Check the documentation:
Search existing issues: Visit the GitHub repository
Join the Discord community: Get help from other users at discord.gg/utftfhSK
Report a bug: If you’ve found a bug, open an issue

Common Error Messages Reference

Error	Cause	Solution
Not authenticated	No auth token	`superserve login`
Agent not found	Invalid agent name/ID	Check with `agents list`
Missing required secret	Secret not set	`secrets set AGENT KEY=VALUE`
Dependency install failed	Invalid package	Fix `requirements.txt`
Session not found	Invalid session ID	Check with `sessions list`
Invalid YAML	Syntax error	Validate YAML syntax
Ambiguous ID	ID prefix matches multiple	Use longer prefix
Request timed out	Network/size issue	Retry or reduce size

Get Started

Core Concepts

CLI Reference

Frameworks

Guides

Authentication Issues

Deployment Issues

Secret Management Issues

Session Issues

Runtime Issues

Configuration Issues

Network and Connection Issues

Best Practices to Avoid Issues

Getting Help

Common Error Messages Reference

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Frameworks

Guides

​Authentication Issues

​Deployment Issues

​Secret Management Issues

​Session Issues

​Runtime Issues

​Configuration Issues

​Network and Connection Issues

​Best Practices to Avoid Issues

​Getting Help

​Common Error Messages Reference

​Next Steps

Build docs developers (and LLMs) love

Authentication Issues

Deployment Issues

Secret Management Issues

Session Issues

Runtime Issues

Configuration Issues

Network and Connection Issues

Best Practices to Avoid Issues

Getting Help

Common Error Messages Reference

Next Steps