Troubleshooting

Common issues and solutions for SystemPrompt

On this page

Solutions to common SystemPrompt issues.

Database Issues

Connection Refused

Error: Connection refused (os error 111) or could not connect to server

Solutions:

  1. Check PostgreSQL is running:

    docker ps | grep postgres
# or
systemctl status postgresql

  2. Verify connection settings in your profile:

    systemprompt admin config show | grep database

  3. Check PostgreSQL is accepting connections:

    psql -h localhost -U systemprompt -d systemprompt

Migration Failures

Error: migration failed or relation does not exist

Solutions:

  1. Check migration status:

    systemprompt infra db status

  2. Re-run migrations:

    systemprompt infra db migrate

  3. For a fresh start (development only):

    docker-compose down -v
docker-compose up -d
systemprompt infra db migrate

SQLx Offline Mode Issues

Error: error returned from database: relation does not exist during build

Solutions:

  1. Ensure SQLx cache is generated:

    cargo sqlx prepare --workspace

  2. Build with offline mode:

    SQLX_OFFLINE=true cargo build

  3. Verify .sqlx/ directory exists and is committed.

Authentication Issues

Login Fails

Error: authentication failed or invalid credentials

Solutions:

  1. Clear existing session:

    systemprompt admin session clear

  2. Re-login:

    systemprompt cloud auth login

  3. Check browser allows popups for auth flow.

Token Expired

Error: token expired or unauthorized

Solutions:

  1. Refresh authentication:

    systemprompt cloud auth refresh

  2. If refresh fails, re-login:

    systemprompt cloud auth login

OAuth Scope Errors

Error: insufficient scope or forbidden

Solutions:

  1. Check agent/tool requires scope you have:

    systemprompt admin agents show <agent_name>

  2. Verify your user has required roles:

    systemprompt admin users show <your_user_id>

MCP Issues

Server Not Found

Error: MCP server not found or 404

Solutions:

  1. Check server is registered:

    curl http://localhost:3000/api/v1/mcp/registry

  2. Sync MCP config:

    systemprompt cloud sync local mcp --direction to-db -y

  3. Restart services:

    systemprompt infra services restart --all

Tool Execution Fails

Error: tool execution failed or timeout

Solutions:

  1. Check MCP server logs:

    systemprompt infra logs --service mcp

  2. Test server directly:

    systemprompt plugins mcp test <server_name>

  3. Verify binary exists and is executable:

    ls -la target/release/mcp-*

Claude Desktop Connection

Error: Can't connect from Claude Desktop

Solutions:

  1. Verify SystemPrompt is running:

    curl http://localhost:3000/health

  2. Check Claude Desktop config:

    {
  "mcpServers": {
    "your-server": {
      "url": "http://localhost:3000/api/v1/mcp/your-server/mcp",
      "transport": "streamable-http"
    }
  }
}

  3. Restart Claude Desktop after config changes.

Build Issues

Cargo Build Fails

Error: Compilation errors

Solutions:

  1. Ensure Rust 1.75+:

    rustc --version
rustup update

  2. Clean and rebuild:

    cargo clean
cargo build

  3. Update dependencies:

    cargo update

Extension Not Loading

Error: Extension not discovered at runtime

Solutions:

  1. Verify register_extension! macro is present.

  2. Ensure crate is linked in Cargo.toml.

  3. Check for use extension_crate as _; in main.

Content Issues

Content Not Syncing

Error: Content changes not appearing

Solutions:

  1. Sync content to database:

    systemprompt cloud sync local content --direction to-db -y

  2. Check content directory:

    ls -la services/content/

  3. Verify frontmatter is valid YAML.

404 on Published Content

Error: Content returns 404 after publishing

Solutions:

  1. Publish content job:

    systemprompt infra jobs run publish_content

  2. Check content is marked public:

    public: true

  3. Verify URL pattern matches slug.

Performance Issues

Slow Queries

Solutions:

  1. Check database indexes:

    SELECT indexname, tablename FROM pg_indexes WHERE schemaname = 'public';

  2. Increase connection pool:

    database:
  pool:
    max_connections: 20

  3. Enable query logging to find slow queries.

High Memory Usage

Solutions:

  1. Check service memory:

    docker stats

  2. Reduce connection pool if not needed.

  3. Set memory limits in Docker Compose.

Getting Help

If these solutions don't resolve your issue:

  1. Check GitHub Issues
  2. Search existing discussions
  3. Open a new issue with:
    • SystemPrompt version (systemprompt --version)
    • Error message and stack trace
    • Steps to reproduce
    • Relevant configuration (without secrets)