Troubleshooting

The following table lists common issues encountered during BuildNinja setup and operation, along with their respective solutions.

Category	Problem	Solution
Server Issues	Port already in use	Change the port in Environment Variables. Update BN_SERVER_PORT if the default (8800) conflicts with another process.
Server Issues	Cannot connect to database	Verify MongoDB credentials and URI, and ensure the MongoDB server is running and accessible from the BuildNinja server host.
Server Issues	SSL errors	Check and verify certificate file paths (BN_SERVER_SSL_CERT, BN_SERVER_SSL_KEY) and permissions.
Server Issues	Web UI not loading	Review firewall settings, ensure the configured port is open, and inspect server logs for startup or network errors.
Agent Issues	Port already in use	Change the port defined in BN_AGENT_PORT if it conflicts with another process.
Agent Issues	Agent fails to register	Ensure BN_AGENT_SERVER_URL is correct and reachable from the agent host.
Agent Issues	Agent shows “Offline” in dashboard	Restart the agent and check its logs. Verify that BN_AGENT_NAME and BN_AGENT_SELFURL are unique and correctly configured.
Agent Issues	Permission denied on workdir	Confirm that the directory specified in BN_AGENT_DATA_DIR has proper read/write permissions.
Network Issues	Server can’t reach agent	Ensure the URL in BN_AGENT_SELFURL is accessible from the server (no firewall restrictions, correct IP/domain).
Network Issues	Agent logs show “Connection refused”	Confirm the BuildNinja server is running and that BN_AGENT_SERVER_URL is correct.
System Issues	Agent unexpectedly shuts down	Check available disk space and review agent logs for fatal errors or system interruptions.