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

# Troubleshooting the Nasiko server

> Startup, port, Docker, and build problems when you run Nasiko yourself.

This page is for running Nasiko yourself.

Problems with coding agents, reporting, or routing are covered in [Troubleshooting coding agents](https://docs.nasiko.com/coding-agents/troubleshooting.md). Problems specific to `nasiko up` are in [Install and connect](https://docs.nasiko.com/install.md#troubleshooting-nasiko-up).

## Starting the server

**`docker: command not found`.** Install [Docker](https://docs.docker.com/get-docker/) and make sure the engine is running.

**`docker-compose` fails, or `depends_on` conditions are rejected.** You're using the legacy v1 binary. Use `docker compose` (with a space), from the Compose V2 plugin.

**`permission denied ... Docker daemon socket`.**

* macOS and Windows: start Docker Desktop and wait until the engine is running.
* Linux and WSL: add yourself to the `docker` group, then log out and back in:

  ```bash theme={null}
  sudo usermod -aG docker "$USER"
  newgrp docker
  ```

**`failed to connect to Postgres`, or the server can't reach Postgres.** The backing services aren't ready yet. Run `docker compose up -d` and wait until `docker compose ps` shows them as `healthy`.

**`invalid SECRETS_ENCRYPTION_KEY` or `Invalid padding`.** The key must be base64 of exactly 32 bytes. Generate a new one:

```bash theme={null}
sed -i.bak "s/^SECRETS_ENCRYPTION_KEY=.*/SECRETS_ENCRYPTION_KEY=$(openssl rand -base64 32)/" .env
```

Only do this on a fresh install. Secrets already stored can't be decrypted with a new key.

**`SEED_TOOLKITS is set but COMPOSIO_API_KEY is not`.** `SEED_TOOLKITS` is optional. Set `COMPOSIO_API_KEY` as well, or leave both unset if you don't need Composio. See [Server configuration](https://docs.nasiko.com/self-hosting/configuration.md#mcp-gateway).

**`address already in use` on ports 9000, 4317, or 4318.** Another process holds the port. Find it with `lsof -i :9000`. On Windows this is usually two Docker engines running at once, Docker Desktop and a native engine inside WSL. Keep one, run `wsl --shutdown`, reopen your terminal, and run `docker compose up -d` again. See [Services and ports](https://docs.nasiko.com/self-hosting/deploy.md#services-and-ports).

**The dashboard won't load.** Check that `docker compose ps` shows `server` as `Up`, then open [http://localhost:8080](http://localhost:8080). Follow its logs with `docker compose logs -f server`.

**Changes to `.env` have no effect.** Run `docker compose up -d`. `docker compose restart` doesn't reload the environment.

## Deployed agents

**An agent logs `[Errno -2] Name or service not known` (Linux).** Docker Engine on Linux doesn't provide `host.docker.internal`. Recreate the agent with `--add-host host.docker.internal:host-gateway`, or set `MCP_GATEWAY_PUBLIC_URL` to the Docker bridge IP. See [Deploy the stack](https://docs.nasiko.com/self-hosting/deploy.md).

**Uploading an agent fails with `500` and `agents_owner_id_fkey`.** Your sign-in is from a database that has since been reset. Sign out and back in. If that doesn't help, reset the local stack and sign in fresh. This deletes all local data:

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

## Building from source

The [install script](https://docs.nasiko.com/install.md#install-the-cli) avoids all of these. They apply when you build the CLI or server with `cargo`.

| Error | Fix |
| - | - |
| Windows: `link.exe not found` or `linker 'cc' not found` | Install the MSVC C++ build tools, then reopen the terminal: `winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"` |
| Windows: `dlltool ... Invalid bfd target` | A 32-bit MinGW (`C:\MinGW`) can't build 64-bit. Install 64-bit MinGW-w64, for example `winget install MSYS2.MSYS2`, and put `C:\msys64\mingw64\bin` on `PATH` ahead of `C:\MinGW`. Or switch to the MSVC toolchain. |
| macOS: `linker 'cc' not found` | `xcode-select --install` |
| Linux: `linker 'cc' not found`, or OpenSSL / `pkg-config` errors | `sudo apt install -y build-essential pkg-config libssl-dev` (or your distribution's equivalent) |
| The first build is very slow | Normal: it compiles the whole workspace. Build from a native clone, not a mounted or network filesystem. |

## Windows and WSL

**`: command not found` when sourcing `.env`.** Windows line endings break `source` in bash. Convert the file:

```bash theme={null}
sed -i 's/\r$//' server/.env
```

**`ext4.vhdx: path not found` from WSL.** The WSL distribution is corrupted. Reinstall it, which deletes its files:

```powershell theme={null}
wsl --unregister Ubuntu
wsl --install -d Ubuntu
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.