Troubleshooting

This page lists common issues you may encounter and how to resolve them.

No CSV files found

Symptoms:

• list-inputs prints “No CSV files found”

• run prints “No CSV files found.”

Fix:

• Confirm input.input_dir points to the folder containing your CSV exports

• Confirm input.file_glob matches your files (for example *.csv)

• Confirm file extension/case matches what your OS/filesystem shows

Invalid config / pre-flight checks failing

Symptoms:

• validate-config fails

• run fails early with “Invalid config”

Fix:

• Start from config/config.example.yaml and apply only necessary changes

• Ensure your YAML indentation is correct (spaces, not tabs)

• Confirm required fields for enabled integrations are present (endpoints, usernames, etc.)

Missing OpenAI API key

Symptoms:

• validate-config fails because OPENAI_API_KEY is not present

• run fails (non-dry-run)

Fix:

• Set OPENAI_API_KEY in your environment

• Prefer env vars over hardcoding openai.api_key into YAML

• If you only want to test ingestion/output structure, run:

  • miyabi-qualys-ai-triage-pack run --config config/config.yaml --dry-run

Slack integration errors

Common symptoms:

• “Missing Slack bot token …”

• “Slack channel not found …”

Fix:

• Ensure notifications.enabled: true

• Ensure integrations.slack.enabled: true

• Provide the bot token via SLACK_BOT_TOKEN (recommended) or integrations.slack.bot_token

• For channels:

  • Use a valid channel name (like #security-jobs) that the bot can access, or

  • Configure the channel ID (C…/G…) if your workspace/channel discovery is restricted

Email integration errors (SendGrid/SMTP)

Symptoms:

• SendGrid: “Missing SendGrid API key …”

• SMTP: authentication or TLS errors, connection refused/timeouts

Fix:

• Ensure notifications.enabled: true

• Enable only one email method at a time unless you intentionally want both:

  • integrations.sendgrid.enabled or integrations.smtp.enabled

• Set SENDGRID_API_KEY (SendGrid) or configure SMTP host/port/TLS/credentials

• Confirm to_emails is configured (otherwise notifications may do nothing)

ZIP attachment/upload not included

Symptoms:

• Slack message includes a warning about ZIP size or missing index.html

• Email body mentions ZIP not included due to size limit

Fix:

• Confirm the pipeline produced output/<csv_name>/index.html

• Increase the size limit (Slack: report_zip_max_mb, email: report_zip_max_mb) only if acceptable

• Reduce attachment size by configuring include/exclude patterns:

  • report_zip_include_patterns

  • report_zip_exclude_patterns

OpenSearch errors

Symptoms:

• Authentication errors (401/403), TLS verification errors, timeouts

Fix:

• Confirm integrations.opensearch.enabled: true

• Confirm endpoint and auth settings:

  • API key via OPENSEARCH_API_KEY (recommended) or integrations.opensearch.auth.api_key

  • Or basic auth (username + password/env var)

• For TLS issues in dev/local:

  • Set integrations.opensearch.tls_verify: false (dev only)

Metabase/Postgres errors

Symptoms:

• Connection refused, authentication failure, SSL mode errors

Fix:

• Confirm integrations.metabase.enabled: true

• Confirm host/port/dbname/username/password (prefer METABASE_PG_PASSWORD)

• Ensure the database is reachable from where the tool runs

• Confirm sslmode matches your Postgres deployment requirements

Expected behavior:

• The tool will create tables (idempotently) and then insert:

  • raw vulnerabilities

  • report runs

  • report items (Top X)

Syslog / Splunk HEC issues

Symptoms:

• Timeouts, connection errors, events missing downstream

Fix:

• Confirm the receiver endpoint is reachable from the machine running the tool

• For syslog:

  • UDP can drop messages; prefer TCP when you need higher reliability

• For Splunk:

  • Confirm HEC token (SPLUNK_HEC_TOKEN) and endpoint URL

  • Confirm TLS verification settings match your environment

HTML looks “broken” after upgrades or when evidence contains markup

If you generated outputs with an older version or suspect evidence content affected rendering, you can normalize outputs:

Normalize outputs

miyabi-qualys-ai-triage-pack normalize-assets --config config/config.yaml --output-dir output

This will:

• Re-copy assets into each output directory

• Optionally rewrite index.html from run.json (when available)