> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpdeploy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

## Deployment errors

### Repository not found

**Error**: "No repositories found" or "Repository not accessible"

**Fix**: Install the GitHub App and grant access to your repository.

1. Go to **Settings** in your dashboard
2. Click **Install GitHub App**
3. Select the repositories you want to deploy
4. Return to the dashboard and refresh

### Build failed

**Error**: Deployment stuck at "Building" or shows "Build failed"

**Common causes**:

* Missing `requirements.txt` or `pyproject.toml`
* Syntax errors in your code
* Missing dependencies

**Fix**:

1. Check build logs in your deployment details
2. Ensure your code runs locally: `python main.py`
3. Verify all dependencies are listed in your requirements file

### Deployment timeout

**Error**: "Deployment timed out" or stuck at "Deploying"

**Cause**: Server doesn't start within 30 seconds.

**Fix**:

1. Ensure your server starts quickly
2. Check for blocking operations at startup
3. Verify your server listens on the correct port

## Runtime errors

### 502/503 errors

**Error**: "Server unavailable" or bad gateway errors

**Fix**:

1. Check deployment logs for startup errors
2. Verify your MCP server implements the protocol correctly
3. Ensure the server responds to health checks at `/health`

### Protocol errors

**Error**: "Invalid JSON-RPC" or MCP protocol errors

**Fix**: Verify your server follows MCP spec:

```json theme={null}
// Valid MCP response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  }
}
```

### Cold start delays

**Symptom**: First request takes several seconds on Free plan.

**Cause**: Scale-to-zero servers sleep after 15 minutes of inactivity.

**Solutions**:

* Wait a few seconds for the server to wake up
* Upgrade to a paid plan for always-on servers

## Authentication errors

### Invalid token

**Error**: 401 Unauthorized when OAuth is enabled

**Fix**:

1. Verify your token is valid and not expired
2. Check the `Authorization Server URL` in deployment settings
3. Ensure the token audience matches your server URL

### Missing scopes

**Error**: 403 Forbidden with scope errors

**Fix**: Ensure your token includes all required scopes configured in deployment settings.

## Logs

### Access build logs

1. Go to your dashboard
2. Click on a deployment
3. View the **Build Logs** section

### Access runtime logs

1. Go to your dashboard
2. Click on a deployment
3. View the **Runtime Logs** section

## Still stuck?

<Card title="Contact Support" icon="envelope" href="mailto:max@mcpdeploy.dev">
  Email [max@mcpdeploy.dev](mailto:max@mcpdeploy.dev) with your deployment ID and error details.
</Card>