Skilder Logo

Troubleshooting

Solutions for common Skilder issues including MCP server connections, skill visibility, OAuth integrations, runtime problems, and API keys.

If your problem is not listed here, reach out to support at support@skilder.ai.

MCP Server Not Connecting

Symptoms: Server status shows "Disconnected" or "Error". Agent cannot discover tools.

Check the runtime status

  1. Open Workspace settings > MCP Servers.
  2. Find the server and check its status indicator.
  3. If the status is Disconnected, try restarting the server.

Verify network connectivity

Confirm your network allows outbound HTTPS connections to *.skilder.ai.

curl -I https://mcp.skilder.ai/health

A 200 response means the connection is healthy. If the request times out, check your firewall or proxy settings.

Skills Not Appearing for Agents

Symptoms: Agent connects to Skilder but cannot see or use specific skills.

Check API key permissions

  1. Open Workspace settings and select the API Keys tab.
  2. Find the API key your agent uses.
  3. Verify the key has access to the workspace containing the skill.

Verify skill assignment

Skills must be assigned to a Hat, and the Hat must be active for the agent's session.

  1. Click Skills in the top navigation and confirm the skill exists inside a hat.
  2. Check that the skill is included in at least one hat.
  3. Confirm the API key belongs to the same workspace.

Confirm the MCP server is running

Skills depend on the MCP servers that provide their tools. If the underlying server is stopped, the skill's tools are unavailable.

  1. Open Workspace settings > MCP Servers.
  2. Verify every server referenced by the skill shows Connected.

OAuth Integration Failures

Symptoms: "Authorization failed", "Invalid redirect URI", or token errors when connecting external services.

Redirect URI mismatch

OAuth providers require an exact redirect URI match. Verify the redirect URI in your OAuth app configuration matches:

https://YOUR_SKILDER_DOMAIN/oauth/callback

Replace YOUR_SKILDER_DOMAIN with your actual deployment domain (for example, app.skilder.ai). The exact URL depends on your deployment. Check for trailing slashes, protocol (https not http), and exact path.

Token expiry

OAuth tokens expire. If an integration worked before but stopped:

  1. Open Workspace settings > Integrations.
  2. Find the affected integration.
  3. Click Reconnect to re-authorize.

Required scopes

Some integrations need specific OAuth scopes. Check the integration's documentation page in Skilder for the list of required scopes, then verify your OAuth app grants them.

Runtime Issues

Symptoms: Servers fail to start or runtimes show as unavailable.

Cloud runtime unavailable

If the cloud runtime is unavailable:

  1. Check the Skilder status page for outages.
  2. Verify your network allows outbound HTTPS connections to *.skilder.ai.
  3. Check the server's configuration in Skilder for missing environment variables or required settings.

API Key Problems

Symptoms: 401 Unauthorized or 403 Forbidden responses when connecting agents.

Expired key

API keys can have an expiration date. Check the key's status:

  1. Open Workspace settings and select the API Keys tab.
  2. Look for an "Expired" label next to the key name.
  3. Create a new key if the current one has expired.

Wrong key format

Skilder API keys use the WSK_ prefix (workspace keys) or USK_ prefix (user keys). Keys must be passed as a Bearer token in the Authorization header:

# Correct
curl -H "Authorization: Bearer WSK_xxxxx..." https://mcp.skilder.ai/sse

# Wrong - missing "Bearer" prefix
curl -H "Authorization: WSK_xxxxx..." https://mcp.skilder.ai/sse

If your key does not start with WSK_ or USK_, it may be invalid or from an older version. Generate a new key from Workspace settings > API Keys.

Key does not match workspace

Each API key belongs to a specific workspace. If you switched workspaces, generate a new key for that workspace.

Test the key

Verify the key works by making a direct request:

curl -v -H "Authorization: Bearer YOUR_API_KEY" https://mcp.skilder.ai/health

A 200 response confirms the key is valid. A 401 means the key is invalid or expired.

General Debugging Tips

Check the runtime health

Open Workspace settings > MCP Servers and review the health indicator for each server. Green means healthy, yellow means degraded, red means down.

Clear browser cache

Some UI issues resolve by clearing cached data:

  1. Open your browser's developer tools (F12 or Cmd+Option+I).
  2. Right-click the refresh button.
  3. Select Empty Cache and Hard Reload.

Verify service status

Check that all Skilder services are operational:

Command Palette Not Responding

Symptoms: Pressing Cmd+K (macOS) or Ctrl+K (Windows/Linux) does not open the command palette.

The command palette provides quick navigation, workspace switching, and theme changes. If it does not respond:

  1. Make sure the browser tab with Skilder is focused (click inside the app first).
  2. Check that no other browser extension or application is intercepting the Cmd/Ctrl+K shortcut.
  3. Try clearing your browser cache and performing a hard reload (see above).
  4. If the issue persists, use the top navigation bar to access the same features manually.

Still stuck?

Configuration

Environment variables and configuration options for Skilder deployments — backend, frontend, runtime, and infrastructure.