Troubleshooting

Common issues and solutions when using NeoRun.

Build Failures

”No entrypoint detected”

NeoRun’s analysis agent couldn’t find a start command.

Fix: Add one of these to your repo:

• A Dockerfile with a valid CMD or ENTRYPOINT
• A start script in package.json
• A main.py or app.py for Python projects
• A Procfile with a web process

”Dependency installation failed”

Package installation timed out or encountered errors.

Common causes:

• Private dependencies without credentials
• Platform-specific packages (e.g., Windows-only)
• Incompatible Python/Node.js version

Fix:

• Ensure all dependencies are publicly accessible
• Add a .python-version or .nvmrc file to pin the runtime version
• Use a Dockerfile for full control over the build environment

”Build timed out”

Builds have a maximum duration of 15 minutes (free tier) or 30 minutes (pro).

Fix:

• Use a smaller base image
• Add a .dockerignore to exclude large files
• Pre-build heavy dependencies in a custom base image

”Image verification failed”

The built container failed health checks.

Fix:

• Ensure your app binds to 0.0.0.0 (not localhost or 127.0.0.1)
• Expose the correct port (check logs for the detected port)
• Add a health check endpoint at / or /health

Pod Issues

Pod shows “Stopped” immediately

The container exited right after starting.

Check:

1. View pod logs for error messages
2. Ensure the app doesn’t exit after startup
3. Check memory usage — pods have a 2GB RAM limit (free tier)

“Port not reachable”

The pod is running but the URL returns an error.

Fix:

• Your app must listen on the port specified by the PORT environment variable
• Default port is 3000; NeoRun detects common framework ports automatically
• Bind to 0.0.0.0, not localhost

Pod URL returns 502/504

The pod is running but not responding to HTTP requests.

Fix:

• Check if the app needs a warm-up period
• Increase the health check timeout
• Ensure the app handles HTTP requests (not just WebSocket or TCP)

GPU Issues

”GPU quota exceeded”

Free tier users get 1 GPU pod with max 4GB VRAM.

Fix:

• Stop existing GPU pods before creating new ones
• Upgrade to a paid plan for higher GPU quotas
• Use CPU-only mode for development

”CUDA out of memory”

The model requires more VRAM than available.

Fix:

• Use a smaller model variant (e.g., 7B instead of 13B for LLMs)
• Enable model quantization (4-bit or 8-bit)
• Set PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

”No GPU detected in container”

The container can’t access the GPU.

Fix:

• Ensure your Dockerfile uses an NVIDIA CUDA base image
• Don’t override the NVIDIA runtime configuration
• Check that GPU is enabled in your deployment settings

Authentication Issues

”Session expired”

Your login session has timed out.

Fix: Log in again at neorun.dev/auth/login.

”API key invalid”

The API key has been revoked or expired.

Fix:

• Check the key’s expiration date in Settings → API Keys
• Generate a new key if the old one has expired
• Ensure the key is correctly copied (starts with neo_sk_)

Getting Help

If your issue isn’t listed here:

1. Check the build logs in the deployment detail page
2. Review the FAQ for common questions
3. Open an issue on GitHub