FAQ

The short answers. Each links to the page with the full story.

Can two watchers run on one instrument?

No. Each instrument can have at most one active watcher at a time. A second registration fails with “instrument already has an active watcher” and prints the existing watcher's id. Deregister the old one first; see Managing watchers → Deregistering a watcher.

What happens if I revoke a token a watcher is using?

The watcher starts getting 401 Unauthorized on its next heartbeat or API call. Create a new token, re-run data-hub-watcher init on the PC to enter it, and restart the watcher. See Managing tokens → After revoking a token.

I'm not an admin, how do I get a token?

You can't mint tokens yourself; only admins can. Ask an admin to issue you one (it'll start with dhub_). Members can view the token audit list but not create or delete tokens. See Security & permissions.

Why aren't my existing files uploading on staging?

By design. On staging and preview, the watcher records files already on disk as a baseline and uploads only files created after setup, so test environments aren't flooded with history. production uploads the backlog. Override with initial_scan: full; see the Configuration reference.

Can one PC talk to both staging and production?

Yes. A PC keeps a separate registration, credentials, and local state per environment, and you switch with data-hub-watcher config set-environment. A running watcher keeps using the old environment until restarted. See Switching environments.

How do I control which files get picked up?

Two settings: file patterns (globs like *.csv that select files) and run detection (how matched files are grouped into runs). Note glob matching is case-sensitive on some systems (*.csv ≠ data.CSV). See Run detection and Troubleshooting → Files aren't being detected.

What's the difference between auto and manual upload mode?

In auto mode files upload immediately after detection. In manual mode runs are reported but files wait for server approval through the upload queue (polled on each heartbeat). See Upload modes.

How do I upload a file by hand?

data-hub-watcher upload --file /path/to/file.csv --run-id RUN001. Add --dry-run to preview. See the CLI reference.

Will an upgrade interrupt a run in progress?

Normally no: the auto-updater only upgrades during a quiet window when no files have uploaded and no run has been reported recently. The exception is a release an admin flags mandatory, which skips that guard. See Upgrading the watcher.

Does the watcher need AWS credentials?

No. The web app issues short-lived pre-signed S3 URLs, and the watcher uploads directly to those; it never holds AWS credentials. See Architecture.

Where are the logs?

~/.data-hub/watcher.log on macOS/Linux, C:\ProgramData\DataHubWatcher\watcher.log on Windows (the CLI and the service share one file). See Troubleshooting → Where are the logs?.