> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for self-hosted Stormkit instances

This guide covers common issues you may encounter when running a self-hosted Stormkit instance and their solutions.

## Installation Issues

### Docker Not Found

**Problem:** Installation script fails with "docker: command not found".

**Solution:**

<Steps>
  <Step title="Install Docker">
    Follow the official Docker installation guide for your platform:

    * [Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
    * [Debian](https://docs.docker.com/engine/install/debian/)
    * [Fedora](https://docs.docker.com/engine/install/fedora/)
    * [macOS](https://docs.docker.com/desktop/install/mac-install/)
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    docker --version
    docker compose version
    ```
  </Step>

  <Step title="Retry Installation">
    ```bash theme={null}
    curl -sSL https://www.stormkit.io/install.sh | sh
    ```
  </Step>
</Steps>

### Permission Denied Errors

**Problem:** Docker commands fail with "permission denied" errors.

**Solution:**

<CodeGroup>
  ```bash Linux theme={null}
  # Add your user to the docker group
  sudo usermod -aG docker $USER

  # Log out and log back in, or run:
  newgrp docker

  # Verify docker works without sudo
  docker ps
  ```

  ```bash Alternative: Use sudo theme={null}
  # Run docker commands with sudo
  sudo docker compose up -d
  ```
</CodeGroup>

<Warning>
  On Linux, you may need to log out and log back in for group membership changes to take effect.
</Warning>

## Database Issues

### Database Connection Failed

**Problem:** Services fail to start with "connection refused" or "database does not exist" errors.

**Solution:**

<Steps>
  <Step title="Check Database Service">
    ```bash theme={null}
    docker compose ps db
    ```

    Ensure the database container shows as "Up" or "running".
  </Step>

  <Step title="Check Database Logs">
    ```bash theme={null}
    docker compose logs db
    ```

    Look for initialization errors or authentication failures.
  </Step>

  <Step title="Verify Environment Variables">
    ```bash .env theme={null}
    POSTGRES_HOST=db
    POSTGRES_PORT=5432
    POSTGRES_DB=stormkit_db
    POSTGRES_USER=stormkit_admin
    POSTGRES_PASSWORD=your_password
    POSTGRES_SSL=disable
    ```

    Ensure all PostgreSQL variables are set correctly.
  </Step>

  <Step title="Restart Services">
    ```bash theme={null}
    docker compose down
    docker compose up -d
    ```
  </Step>
</Steps>

### Database Migration Errors

**Problem:** Services fail with "migration failed" or "table does not exist" errors.

**Solution:**

```bash theme={null}
# Stop services
docker compose down

# Remove database volume (WARNING: This deletes all data)
docker volume rm stormkit_postgres_data

# Start services fresh
docker compose up -d

# Monitor logs for successful migration
docker compose logs -f workerserver hosting
```

<Warning>
  Removing the database volume will delete all data. Only do this for fresh installations or if you have a backup.
</Warning>

## Redis Issues

### Redis Connection Failed

**Problem:** Services log "redis: connection refused" errors.

**Solution:**

<Steps>
  <Step title="Check Redis Service">
    ```bash theme={null}
    docker compose ps redis
    ```
  </Step>

  <Step title="Verify Redis Address">
    ```bash .env theme={null}
    REDIS_ADDR=redis:6379
    ```

    For Docker Compose, use the service name `redis` (not `localhost`).
  </Step>

  <Step title="Test Redis Connection">
    ```bash theme={null}
    docker compose exec redis redis-cli ping
    # Should return: PONG
    ```
  </Step>

  <Step title="Restart Redis">
    ```bash theme={null}
    docker compose restart redis
    ```
  </Step>
</Steps>

## API and Web Interface Issues

### API Endpoints Return 500 Errors

**Problem:** When accessing the application, API endpoints like `/api/auth/providers` and `/api/instance` return 500 Internal Server Error.

**Solution:**

This is typically caused by DNS resolution issues with `api.localhost`.

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Add api.localhost to your hosts file
  echo "127.0.0.1       api.localhost" | sudo tee -a /etc/hosts

  # Verify it resolves correctly
  ping -c 1 api.localhost

  # Restart services
  docker compose restart hosting workerserver
  ```

  ```bash Windows (PowerShell as Admin) theme={null}
  # Open hosts file in notepad
  notepad C:\Windows\System32\drivers\etc\hosts

  # Add this line:
  127.0.0.1       api.localhost

  # Save and close
  ```
</CodeGroup>

<Note>
  On Windows, you need to open Notepad (or any text editor) with administrative privileges to edit the hosts file.
</Note>

### Cannot Access Web Interface

**Problem:** Browser shows "connection refused" when accessing Stormkit.

**Solution:**

<Steps>
  <Step title="Verify Services Running">
    ```bash theme={null}
    docker compose ps
    ```

    All services should show as "Up".
  </Step>

  <Step title="Check Port Bindings">
    ```bash theme={null}
    docker compose ps hosting
    ```

    Verify ports 80 and 443 are mapped correctly.
  </Step>

  <Step title="Check Firewall">
    Ensure your firewall allows incoming connections on ports 80 and 443.

    ```bash theme={null}
    # Ubuntu/Debian with ufw
    sudo ufw allow 80/tcp
    sudo ufw allow 443/tcp

    # Fedora/RHEL with firewalld
    sudo firewall-cmd --add-service=http --permanent
    sudo firewall-cmd --add-service=https --permanent
    sudo firewall-cmd --reload
    ```
  </Step>

  <Step title="Verify URL Configuration">
    ```bash .env theme={null}
    STORMKIT_APP_URL=https://yourdomain.com
    STORMKIT_API_URL=https://api.yourdomain.com
    ```

    Ensure these match your actual domain.
  </Step>
</Steps>

### HTTPS/TLS Certificate Errors

**Problem:** Browser shows SSL/TLS certificate warnings.

**Solution:**

<Steps>
  <Step title="Configure ACME Email">
    ```bash .env theme={null}
    STORMKIT_HTTPS=on
    STORMKIT_ACME_EMAIL=admin@yourdomain.com
    ```

    This enables automatic Let's Encrypt certificates.
  </Step>

  <Step title="Verify Domain DNS">
    Ensure your domain points to your server's IP:

    ```bash theme={null}
    dig yourdomain.com +short
    dig api.yourdomain.com +short
    ```
  </Step>

  <Step title="Restart Hosting Service">
    ```bash theme={null}
    docker compose restart hosting
    ```
  </Step>

  <Step title="Check Certificate Logs">
    ```bash theme={null}
    docker compose logs -f hosting | grep -i "acme\|certificate"
    ```
  </Step>
</Steps>

<Note>
  Let's Encrypt requires your domain to be publicly accessible on port 80 for the HTTP-01 challenge.
</Note>

## Authentication Issues

### GitHub App Creation Failed

**Problem:** Creating a GitHub App from the admin interface fails.

**Solution:**

<Steps>
  <Step title="Verify Callback URL">
    Ensure `STORMKIT_APP_URL` is set correctly and accessible from the internet.
  </Step>

  <Step title="Check GitHub API Access">
    ```bash theme={null}
    curl -I https://api.github.com
    ```

    Verify your server can reach GitHub's API.
  </Step>

  <Step title="Review Error Logs">
    ```bash theme={null}
    docker compose logs -f hosting | grep -i "github"
    ```
  </Step>
</Steps>

### OAuth Redirect Mismatch

**Problem:** Git provider authentication fails with "redirect\_uri\_mismatch" error.

**Solution:**

1. **Verify redirect URI** in your Git provider OAuth app settings matches exactly:
   * GitHub: `https://yourdomain.com/auth/github/callback`
   * GitLab: `https://yourdomain.com/auth/gitlab/callback`
   * Bitbucket: `https://yourdomain.com/auth/bitbucket/callback`

2. **Check `STORMKIT_APP_URL`** in `.env` file matches your domain

3. **Ensure HTTPS** is enabled if using a custom domain:
   ```bash .env theme={null}
   STORMKIT_HTTPS=on
   ```

## Deployment Issues

### Deployments Fail or Hang

**Problem:** Deployments remain in "pending" state or fail immediately.

**Solution:**

<Steps>
  <Step title="Check Workerserver Service">
    ```bash theme={null}
    docker compose ps workerserver
    docker compose logs -f workerserver
    ```
  </Step>

  <Step title="Verify Runner Concurrency">
    ```bash .env theme={null}
    STORMKIT_RUNNER_CONCURRENCY=4
    ```

    Ensure this value is appropriate for your server's resources.
  </Step>

  <Step title="Check Disk Space">
    ```bash theme={null}
    df -h
    docker system df
    ```

    Ensure sufficient disk space for builds.
  </Step>

  <Step title="Review Build Logs">
    Check the deployment logs in the Stormkit UI for specific error messages.
  </Step>
</Steps>

### Runtime Installation Fails

**Problem:** Deployments fail with "runtime not found" or "mise installation failed".

**Solution:**

<Steps>
  <Step title="Check Internet Connectivity">
    ```bash theme={null}
    docker compose exec workerserver ping -c 3 github.com
    ```

    Workerserver needs internet access to download runtimes.
  </Step>

  <Step title="Verify Runtime Configuration">
    Go to **Admin** > **System** > **Installed runtimes** and ensure required runtimes are listed.
  </Step>

  <Step title="Enable Auto Install">
    In runtime settings, toggle **Auto install** on to automatically install runtimes from version files.
  </Step>

  <Step title="Check Mise Version">
    Upgrade mise to the latest version from the admin interface.
  </Step>
</Steps>

### Build Cache Issues

**Problem:** Builds are unusually slow or don't use cached dependencies.

**Solution:**

```yaml docker-compose.yaml theme={null}
# Ensure home directory is persisted
services:
  workerserver:
    volumes:
      - workerserver_home:/home/stormkit

volumes:
  workerserver_home:
```

Restart services after adding volume:

```bash theme={null}
docker compose down
docker compose up -d
```

## Performance Issues

### High Memory Usage

**Problem:** Docker containers consume excessive memory.

**Solution:**

<Steps>
  <Step title="Check Container Stats">
    ```bash theme={null}
    docker stats
    ```
  </Step>

  <Step title="Reduce Runner Concurrency">
    ```bash .env theme={null}
    STORMKIT_RUNNER_CONCURRENCY=2
    ```

    Lower values reduce memory usage but slow down parallel builds.
  </Step>

  <Step title="Set Memory Limits">
    ```yaml docker-compose.yaml theme={null}
    services:
      workerserver:
        deploy:
          resources:
            limits:
              memory: 2G
    ```
  </Step>
</Steps>

### Slow Database Queries

**Problem:** Application feels sluggish, database queries are slow.

**Solution:**

```yaml docker-compose.yaml theme={null}
services:
  db:
    environment:
      - POSTGRES_SHARED_BUFFERS=256MB
      - POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
    deploy:
      resources:
        limits:
          memory: 1G
```

## Development Environment Issues

### go: command not found

**Problem:** After running `mise install`, which reports "all tools are installed", running `make dev` fails with "go: command not found".

**Solution:**

The mise tools aren't activated in your shell. Add mise activation to your shell configuration:

<CodeGroup>
  ```bash zsh theme={null}
  # Add mise activation to zsh
  echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

  # Reload configuration
  source ~/.zshrc

  # Verify go is available
  which go
  ```

  ```bash bash theme={null}
  # Add mise activation to bash
  echo 'eval "$(mise activate bash)"' >> ~/.bashrc

  # Reload configuration
  source ~/.bashrc

  # Verify go is available
  which go
  ```

  ```bash fish theme={null}
  # Add mise activation to fish
  echo 'mise activate fish | source' >> ~/.config/fish/config.fish

  # Reload configuration
  source ~/.config/fish/config.fish

  # Verify go is available
  which go
  ```
</CodeGroup>

<Note>
  See [mise activation docs](https://mise.jdx.dev/getting-started.html#_2-activate-mise) for more shell options.
</Note>

### Image Optimization Not Working

**Problem:** Image optimization features don't work in local environment.

**Solution:**

Image optimization is disabled by default on local environments to avoid requiring additional dependencies.

To enable it:

1. Install required system packages (ImageMagick, libvips, etc.)
2. Build a custom Docker image with image optimization libraries
3. See [Custom Images](/self-hosting/custom-images) for detailed instructions

<Note>
  For self-hosted production instances, include image processing libraries in your custom Docker image if needed.
</Note>

## Logging and Debugging

### Enable Debug Logging

Increase log verbosity for troubleshooting:

```bash .env theme={null}
DEBUG=3
```

Higher values (1-5) provide more verbose output.

### View Service Logs

<CodeGroup>
  ```bash All Services theme={null}
  # Follow logs from all services
  docker compose logs -f

  # View last 100 lines
  docker compose logs --tail=100
  ```

  ```bash Specific Service theme={null}
  # Hosting service logs
  docker compose logs -f hosting

  # Workerserver logs
  docker compose logs -f workerserver

  # Database logs
  docker compose logs -f db
  ```

  ```bash Search Logs theme={null}
  # Search for errors
  docker compose logs | grep -i "error"

  # Search for specific term
  docker compose logs -f | grep "deployment"
  ```
</CodeGroup>

### Export Logs for Support

```bash theme={null}
# Export all logs to file
docker compose logs > stormkit-logs.txt

# Export with timestamps
docker compose logs -t > stormkit-logs-$(date +%Y%m%d).txt
```

## Backup and Recovery

### Backup Database

<Steps>
  <Step title="Create Backup">
    ```bash theme={null}
    docker compose exec db pg_dump -U stormkit_admin stormkit_db > backup.sql
    ```
  </Step>

  <Step title="Verify Backup">
    ```bash theme={null}
    ls -lh backup.sql
    ```
  </Step>

  <Step title="Store Securely">
    Copy the backup file to a secure location:

    ```bash theme={null}
    cp backup.sql /path/to/secure/backups/stormkit-$(date +%Y%m%d).sql
    ```
  </Step>
</Steps>

### Restore Database

<Warning>
  Restoring a database will overwrite all current data. Ensure you have a recent backup before proceeding.
</Warning>

```bash theme={null}
# Stop services
docker compose down

# Start only database
docker compose up -d db

# Wait for database to be ready
sleep 5

# Restore backup
docker compose exec -T db psql -U stormkit_admin -d stormkit_db < backup.sql

# Start all services
docker compose up -d
```

### Backup Volumes

```bash theme={null}
# Backup all Docker volumes
docker run --rm \
  -v stormkit_postgres_data:/source:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/postgres-data-backup.tar.gz -C /source .
```

## Getting Help

### Community Support

* **GitHub Issues**: [stormkit-io/stormkit-io](https://github.com/stormkit-io/stormkit-io/issues)
* **GitHub Discussions**: [Community Q\&A](https://github.com/stormkit-io/stormkit-io/discussions)

### Reporting Issues

When reporting issues, include:

1. **Stormkit version** - Check the version in the admin interface
2. **Operating system** and version
3. **Docker version** - `docker --version`
4. **Docker Compose version** - `docker compose version`
5. **Error messages** - Complete error output from logs
6. **Steps to reproduce** - How to trigger the issue
7. **Environment variables** (sanitized) - Remove sensitive values

### Diagnostic Information

```bash theme={null}
# Collect diagnostic information
echo "=== System Info ==="
uname -a

echo "\n=== Docker Version ==="
docker --version
docker compose version

echo "\n=== Service Status ==="
docker compose ps

echo "\n=== Container Stats ==="
docker stats --no-stream

echo "\n=== Disk Usage ==="
df -h
docker system df

echo "\n=== Recent Logs ==="
docker compose logs --tail=50
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/self-hosting/installation">
    Back to installation guide
  </Card>

  <Card title="Runtimes" icon="code" href="/self-hosting/runtimes">
    Configure programming language runtimes
  </Card>

  <Card title="Custom Images" icon="docker" href="/self-hosting/custom-images">
    Build custom Docker images
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/stormkit-io/stormkit-io/issues">
    Report bugs and issues
  </Card>
</CardGroup>