FAQ & troubleshooting

Port already in use

niuniu defaults to port 3000. Change it in ~/.niuniu/config.yaml:

server:
  host: 127.0.0.1
  port: 3001

Or set the environment variable NIUNIU_SERVER_PORT=3001.

SQLite lock errors

If you see database is locked, a previous process likely didn’t exit cleanly.

• Check for lingering niuniu / niuniu-server processes: ps aux | grep niuniu, and kill them.
• Remove the lock files: rm ~/.niuniu/niuniu.db-shm ~/.niuniu/niuniu.db-wal (the data itself is in niuniu.db — don’t delete that).
• If you’re running 3 or more workspaces concurrently, consider switching to PostgreSQL (see Self-Hosted install).

claude command not found

niuniu communicates with Anthropic through the claude CLI, which must be installed separately. See Claude CLI.

# Verify the install
claude --version

If the binary isn’t on your PATH, set its location explicitly in ~/.niuniu/config.yaml:

agent:
  claude_cli_path: /Users/me/.local/bin/claude

Disabling auth

For a personal dev setup you can turn off authentication. Edit ~/.niuniu/config.yaml:

auth:
  enabled: false

Restart niuniu to apply. Do not disable auth in production.

Where is my data?

• Config: ~/.niuniu/config.yaml
• SQLite database: ~/.niuniu/niuniu.db
• Multi-tenant subdirectories: ~/.niuniu/{users,orgs}/<id>/{workspaces,repositories}/

Still stuck?

Open a GitHub issue or reach out through the Team edition console.