Skip to content

troubleshooting.md

Latest commit

 

History

History
73 lines (43 loc) · 3.64 KB

troubleshooting.md

File metadata and controls

73 lines (43 loc) · 3.64 KB
Raw

Troubleshooting

This document lists the common first-setup failures.

bun install warns 'better-sqlite3' is not yet supported in Bun

Node.js was not on PATH during bun install. Without Node.js, Bun runs the better-sqlite3 install script itself, cannot download the prebuilt binary, and tries a source compilation that usually fails. The dashboard then cannot open a database.

Install Node.js 22 (see Requirements), then reinstall:

rm -rf node_modules
bun install

With Node.js on PATH, the warning does not appear and no compiler is necessary.

A pipeline command shows no output for minutes

The first ./scripts/netflow-db.sh run compiles the Rust pipeline in release mode. The compilation takes several minutes and happens one time. Later runs start immediately.

unable to start nfdump executable "nfdump"

The pipeline did not find an nfdump executable. This error can appear after several minutes, because the pipeline compiles and discovers input files first.

Build the pinned fork, then pass its path:

git submodule update --init --recursive
./vendor/scripts/compile-nfdump.sh
./scripts/netflow-db.sh pipeline ... --nfdump target/nfdump/libexec/nfdump

nfdump starts but the pipeline rejects its output

The command used a system nfdump installation. A system nfdump does not have the output mode that the pipeline needs. Pass the pinned fork with --nfdump target/nfdump/libexec/nfdump.

The pipeline stops on a missing member directory

Each member in the dataset sources must be a directory directly under root_path. Check these items in datasets.json:

  • root_path is a real path on this computer, not the /path/to/... placeholder from the example file.
  • Each members name matches a directory name under root_path exactly.

The input directory layout shows the expected structure.

The dashboard shows "No datasets found"

The dashboard did not discover a database at data/<dataset-id>/netflow.sqlite.

  • Run the pipeline to create the database.
  • If the dataset db_path is outside data/, set LOCAL_SQLITE_PATH in .env to the database path.

The dashboard shows "Failed to list datasets"

The server discovered a database but could not read it. Check these items:

  • Each file at data/<dataset-id>/netflow.sqlite is a database that the pipeline produced. Run the verify command against it.
  • If you exported ATLANTIS_DB_DRIVER=d1, the local D1 database needs the migrations from Operations.

Could not start dynamically linked executable: ... workerd

This error comes from the Cloudflare Workers runtime on NixOS. Local SQLite development does not start it. The runtime only starts when you develop against local D1 with ATLANTIS_DB_DRIVER=d1; for that, enable programs.nix-ld in your NixOS configuration.

The charts are empty

The dashboard opened a date range without processed data. Check these items:

  • The pipeline date range covers the dates that you look at. The pipeline only processes the days between --start-date and --end-date.
  • The date range in the dashboard is inside the processed range. A new visit opens at the earliest processed day, but a saved web address keeps its own dates.
  • If the dataset sets default_start_date in datasets.json, that date is inside the processed range. Remove the field to let the pipeline use the earliest processed day.

Run the verify command with --require-data to confirm that the database contains results.