Troubleshooting

Troubleshooting

Bot Fails During Startup

Missing or invalid Telegram token

Symptoms may include token validation or authentication errors when src/bot.py initializes.

Check:

grep -E '^(TELEGRAM_BOT_TOKEN|TELEGRAM_ALLOWED_CHAT_IDS|AI_PROVIDER|AI_MODEL|AI_BASE_URL|AI_API_KEY)=' .env

Do not paste the values into an issue. Rotate any token that has been exposed.

Python cannot import project modules

Run the bot from the repository root:

python src/bot.py

Verify dependencies:

python -m pip install -r requirements.txt
python -m compileall src

Docker Errors

Cannot connect to the Docker daemon

Confirm Docker is running:

docker info

When the bot runs in a container, confirm the socket mount exists:

docker inspect lophiarch-bot --format '{{json .Mounts}}'

Permission denied on docker.sock

The process lacks access to the Docker socket. Review host permissions and the container runtime configuration. Do not make the socket world-writable as a quick fix.

Worker image not found

Build the missing image:

docker build -f Dockerfile.nmap -t lophiarch-nmap:latest .
docker build -f Dockerfile.ffuf -t lophiarch-ffuf:latest .
docker build -f Dockerfile.nuclei -t lophiarch-nuclei:latest .

List expected images:

docker image ls --format '{{.Repository}}:{{.Tag}}' | grep lophiarch

AI Provider Errors

• Unknown provider: use ollama, vllm, lmstudio, llamacpp, gemini, or openai-compatible.
• Connection refused: verify AI_BASE_URL and confirm the model server is listening on an address reachable from the Lophiarch process or container.
• Model not found: verify AI_MODEL; for Ollama, run ollama pull MODEL_NAME.
• 401 or 403: verify AI_API_KEY and provider account permissions.
• 429: reduce request frequency and check the selected provider quota.
• Missing custom endpoint: AI_PROVIDER=openai-compatible requires both AI_BASE_URL and AI_MODEL.
• Invalid tool-call output: confirm the selected model supports reliable OpenAI-compatible function or tool calling.

Gemini-specific compatibility remains available through AI_PROVIDER=gemini, but it is optional and no longer the system-wide dependency. Sanitize provider responses before sharing logs publicly.

Empty Scanner Results

Empty output does not always mean the target is secure.

Check:

• Target formatting and DNS resolution.
• Authorization-scoped network access.
• Scanner container logs or stderr.
• Whether a WAF, rate limit, firewall, or timeout affected the scan.
• Whether the selected mode is appropriate.
• Whether upstream images or templates changed.

PDF Is Not Sent

Confirm that:

• At least one scanner ran before create_pdf_report.
• generated_reports/ is writable.
• The bot can read the generated path.
• Telegram accepts the resulting document.

Container logs may show Failed to send PDF when delivery fails.

Helm Pod Does Not Start

helm lint deploy/helm
kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>

The current chart requires /var/run/docker.sock on the node. Containerd-only nodes will not satisfy this requirement by default.

Opening a Bug Report

Use the Bug Report issue form and include:

• Commit or image tag.
• Deployment method and environment.
• Minimal authorized reproduction.
• Expected and actual behavior.
• Sanitized logs.

Report suspected security vulnerabilities privately instead.