v1.4.0

Troubleshooting

Solutions for common issues when using OWASP Noir.

Hak, the OWASP Noir mascot

Something on fire? Start with the symptom below that matches. Most of these have a one-flag fix.

No Endpoints Found

Symptom: Noir runs but reports 0 endpoints.

  • Check that you are pointing to the correct directory: noir scan ./your-app
  • Verify that your framework is supported: noir list techs
  • Check the detection step in the log. It lists each detected technology; if it says No technologies detected, name the framework yourself with -t: noir scan . -t rails
  • If your framework is not supported, use AI-Powered Analysis to detect endpoints

Scan Takes Too Long

Symptom: Noir takes a long time on large codebases.

  • Use --only-techs to run just those detectors and skip the rest: noir scan . --only-techs rails (--techs is different: it adds techs to the analyzer set without narrowing detection)
  • Use --exclude-techs to skip the analyzers of detected frameworks you don't need (the log marks them (skip))
  • Use --exclude-path to skip vendored or generated trees: --exclude-path "vendor/*,**/node_modules/**"
  • AI responses are cached, so repeat runs on the same code are faster

AI Provider Connection Errors

Symptom: Errors when using --ai-provider.

  • Check the API key you passed in NOIR_AI_KEY, --ai-key-file, or --ai-key
  • For local providers (Ollama, vLLM, LM Studio), check that the server is running
  • Check the provider's default host in the AI Providers table
  • For custom endpoints, use the full URL: --ai-provider=http://your-server:port
  • For ACP providers, set NOIR_ACP_RAW_LOG=1 to see the agent's raw logs

Symptom: The AI analysis stalls, or gives up while the model is still working.

  • Requests fail after NOIR_AI_CONNECT_TIMEOUT (default 10s) if the host is unreachable, and after NOIR_AI_TIMEOUT (default 300s) if the provider accepts the request but never answers
  • Raise NOIR_AI_TIMEOUT when a slow local model legitimately needs longer to generate; lower --ai-max-token to send smaller bundles instead
  • Rate limits (HTTP 429) and transient gateway errors (502, 503, ...) are retried with backoff, up to three attempts in total. If warnings persist, reduce --concurrency or cap the run with --ai-max-requests
  • If a proxy or gateway drops connections that sit idle while the model generates, add --ai-stream (OpenAI-compatible providers)

Docker Permission Issues

Symptom: Permission denied errors when running via Docker.

  • Check that your directory is mounted correctly: docker run --rm -v $(pwd):/tmp ghcr.io/owasp-noir/noir:latest noir scan /tmp
  • On SELinux systems, add :z to the volume mount: -v $(pwd):/tmp:z

Shell Completion Not Working

Symptom: Tab completion doesn't work after installation.

  • If you installed with Homebrew (brew install noir or the owasp-noir/noir tap), completions are set up automatically for bash, zsh and fish. Open a new shell
  • For manual setup, see Shell Completions
  • After setting up, restart your shell or run source ~/.zshrc (or equivalent)

Still Need Help?