Troubleshooting

Connection Issues

"Authentication required" error

• Verify your token is valid and not expired
• Check the Authorization header format: Bearer <token> (note the space after "Bearer")
• For OAuth: try disconnecting and reconnecting in your AI client

"No active project is selected" error

• Interactive sessions: Call semaphor_list_projects to find your project ID, then pass projectId explicitly on project-scoped tools
• Project-token sessions: This shouldn't happen — verify your token includes a projectId
• Stateless HTTP clients: Pass projectId explicitly as a parameter on project-scoped tools

"Project not found or you do not have access"

• Verify the project ID is correct
• Check that your user has access to this project in the Semaphor console
• For tenant users: ensure the tenant has been granted project access

Discovery Issues

"No semantic domains found"

• Semantic domains may not be configured for this project
• Ask your admin to set up semantic domains (see Semantic Domains)
• Use the physical discovery path instead: semaphor_list_connections then semaphor_get_dataset_schema with connection coordinates

"No connections found"

• Verify the project has database connections configured in the Semaphor console
• Check CLS policies — you may not have access to any connections
• For project tokens: ensure the token's security configuration allows connection access

Empty dataset list

• The semantic domain may not have any datasets configured yet
• Check the domain setup in the Semaphor console

Query Issues

"Failed to verify execution context"

• Your token may have expired — generate a new one
• For OAuth sessions: your token may have expired. Reconnect your AI client
• For project tokens: regenerate the token

Query returns empty results

• Verify the table or dataset has data
• Check RLS policies — row-level security may be filtering all rows for your user context
• Try a simpler query first (e.g., SELECT COUNT(*) FROM table_name)

"Connection refused" or timeout errors

• Verify the database connection is active in the Semaphor console
• Check that the database server is accessible from the Semaphor infrastructure
• Try a different connection if available

Client-Specific Issues

Cursor: "Tool not found"

• Restart Cursor after changing mcp.json
• Verify mcp.json is valid JSON (no trailing commas)
• Check that mcp-remote is available: npx mcp-remote --version
• Ensure the configuration is in the correct file (~/.cursor/mcp.json)

Claude: Integration not appearing

• Check that your Claude plan supports MCP integrations
• Try removing and re-adding the integration
• Ensure you completed the OAuth sign-in flow

Getting Help

If you're still experiencing issues:

• Check the Semaphor console for your project, connection, and user status
• Verify your security policies (CLS, SLS, RLS) in the project settings
• Contact support at support@semaphor.cloud