Use this page after an import, run, or listener behaves differently from what you expected. Start with the recorded error and move outward through script state, trigger state, configuration, and platform support. Do not edit SQLite or installed package files to make an error disappear.
Every terminal run record contains:
completed, failed, or cancelled. A completed run that emitted error logs also displays a separate with errors badge.completed means graph execution reached a normal terminal state. A fallible action can take its failure branch and still produce a completed run when the graph handles that failure. failed means execution could not continue. cancelled means a stop request interrupted runtime execution.
Secret plaintext is not intended to appear in logs or stored snapshots. If it does, stop using the affected script, preserve a redacted reproduction, rotate the value, and report a security issue.
BaudBound bounds run history by count, age, and total stored bytes. The default keeps at most 10,000 runs, removes records older than 30 days, and uses at most 1 GiB for run history. Each run record contains its logs and final variable snapshot, so those historical details are removed together.
Configure the limits under [runner]:
[runner]
run_history_max_records = 10000
run_history_max_age_days = 30
run_history_max_bytes = 1073741824
All values must be greater than zero. The runner applies all three limits, so the oldest record is removed when count, age, or storage size reaches its limit. Lowering a limit prunes existing history as soon as the new configuration is applied. New runs are inserted and old runs are pruned in one SQLite transaction.
Retention never deletes installed scripts, approvals, persistent variables, global variables, or encrypted secrets. Increase the limits before an investigation when you need a longer history window.
Monitor is a temporary live view. It keeps the latest 500 events in memory and does not replace Runs or Logs. A monitor omission warning means the UI copy could not be captured without slowing execution. The script event was not rejected. A row marked Rejected is different because it means the real execution queue did not accept the event.
The Logs tab searches messages across all retained runs. Use a run ID to avoid mixing errors from two overlapping executions. Results are paginated, so a search is applied before the page is selected.
For a support case, select the relevant records in Runs and choose Export selected. A single run produces one JSON file. Multiple runs produce a ZIP archive with one JSON file for every run and a manifest. The files include complete stored logs, final variable snapshots, scopes, script identity, trigger identity, timestamps, runner version, platform, and storage schema version. Managed secret values are excluded.
Use Export JSON or Export CSV in Logs when the investigation needs messages from many runs. The current search controls which records are exported. Export includes all matching messages rather than only the visible page.
Open Variables to inspect current persistent and global values together with defaults declared by installed packages. Choose Export variables to save the complete variable inventory as JSON. The export includes stored values, declared defaults, scopes, types, script ownership, runner information, and declaration warnings. Managed secrets are not included. Runtime and node output values belong to one execution and remain in that run's detail view.
JSON exports identify their document structure with a format field. Run files use baudbound.run, log files use baudbound.logs, and variable files use baudbound.variables. The separate format_version number allows BaudBound tools to recognize future structural changes.
Use Clear runs on the Runs page to delete every completed run record stored by the runner. This includes records that are older than the ones currently shown. BaudBound asks for confirmation before deleting them. Running scripts are not stopped and can create new records when they finish.
Use Clear logs on the Logs page when you want to remove stored messages but keep the run records. Run status, identifiers, completion times, and final variable values remain available. BaudBound asks for confirmation before clearing the messages. Running scripts can add new messages after the operation completes.
The desktop receives active run changes directly from the Rust runner. A run does not need to remain active until the next refresh interval. Finished history is refreshed only after the runner has committed its terminal record to SQLite.
BaudBound supports workflows that intentionally run forever. There is no maximum run time and no fixed While or Repeat iteration budget.
The runner keeps service controls responsive by bounding pending triggers for each script and checking cancellation between graph steps and during cancellable waits. Repeated triggers for a script that is already running enter a bounded queue. When that queue is full, the new trigger is rejected with a clear error instead of consuming memory without limit. Different scripts can still run concurrently.
Logs and completed-run variables have separate size limits. When one run produces more retained output than allowed, BaudBound records one suppression or truncation notice and stops growing that stored section. This does not cancel an otherwise healthy endless run. A single active variable that exceeds its runtime size limit fails the operation because it could otherwise exhaust process memory.
To stop an endless run in the desktop app, open Runs, find it under Currently running, and choose Stop. In the CLI, list active runs and use the documented stop command for its run ID. Cancellation is cooperative, so a native operation that cannot be interrupted must return before the run can finish stopping.
HTTP Request logs keep the method, destination scheme, host, port, path, query parameter names, response status, duration, safe headers, body byte counts, and SHA-256 body hashes. Query values and sensitive headers are replaced with [REDACTED].
For JSON and form bodies, common secret fields such as passwords, tokens, cookies, authorization values, API keys, and nested equivalents are redacted before a preview is stored. BaudBound then applies configured secret-value redaction. Control characters are escaped so \r, \n, tabs, and binary-looking data cannot alter the log layout. Unknown binary bodies are represented by metadata and a hash instead of raw bytes.
Previews are bounded and include a truncation marker when content does not fit. These protections cannot recognize every piece of private business data. Do not place unnecessary personal or confidential content in logs, and inspect an export before sharing it.
The shared clock setting changes human readable desktop and CLI timestamps between 12 hour and 24 hour notation. Change it in the desktop Config page or with baudbound config set display.time-format. It does not alter stored timestamps, log order, or CLI JSON values.
Replace SCRIPT with the installed name or ID shown by baudbound script list:
baudbound doctor
baudbound status
baudbound script status
baudbound script inspect SCRIPT
baudbound script approval SCRIPT
baudbound script triggers SCRIPT
baudbound script logs --script SCRIPT --limit 20
Use --json only on commands that document it when collecting structured diagnostics. Human-readable output is intended for people and can change between versions.
| Symptom | First check | Then inspect |
|---|---|---|
| Import rejected | baudbound validate PACKAGE |
Package format, target, version, graph, declarations |
| Script needs attention | Scripts or baudbound script status |
Hash, approval, secrets, compatibility, enablement |
| Manual run rejected | baudbound script inspect |
Manual trigger, approval, policy, target, secrets |
| No automatic event | Monitor, Doctor, and Service | Script enabled, registration, family toggle, OS prerequisite |
| Run failed at a node | Runs and Logs | Node config, resolved variables, native error, failure branch |
| Serial disconnected | Doctor, then Tools | Reader state, detected ports, access, protocol, USB identity, ambiguity |
| Webhook unavailable | Service listener | Bind, port, route, firewall/proxy, body limit |
| Update unavailable | Update dialog/error | HTTPS, release metadata, platform artifact, signature, clock |
The managed .bbs bytes no longer match the SHA-256 hash stored at import/update, or installation did not complete normally. Never replace the managed package in the runner home.
Return to the original editor project, export a new package, and validate it:
baudbound validate PACKAGE
baudbound script update PACKAGE
baudbound script inspect SCRIPT
Review and approve the new revision after the status reports a valid package hash.
Read every problem reported by baudbound script inspect. A run requires a valid installed package, compatible target, current approval, allowed policy, all required secrets, and a usable trigger. A direct manual run also needs a Manual Trigger unless --trigger TRIGGER explicitly selects another valid trigger node.
Enablement controls long-lived trigger registration. It is not required for a direct baudbound script run, but it is required for schedules, listeners, watchers, startup registration, and serial readers.
An update changed the package hash. Inspect the new access declarations and graph, then approve the current revision. Do not attempt to copy or edit approval rows. See Approvals, Capabilities, and Risk.
Confirm all of these:
baudbound script triggers SCRIPT.config.toml.Script lifecycle changes reload automatically at runner.trigger_reload_seconds. Configuration changes require a service restart.
Check physical connectivity, port permissions, baud/data/parity/stop/flow settings, and read_mode. With identity validation enabled, a mismatch intentionally prevents the wrong device from opening. Auto rebind refuses zero or multiple matches. Identical devices should have distinct serial numbers in configuration.
If a scanner beeps, restarts, or disconnects when the runner starts, set dtr_on_open to deasserted. Increase open_stabilization_ms if the device needs more than 500 milliseconds before it is ready. Bytes received during this wait are discarded. Doctor shows the configured DTR policy and wait time for each reader.
Open Doctor and find the affected Serial Input row. Active port is the port currently owned by the shared device connection. Message framing shows the selected mode and how many bytes are waiting for completion. Last error shows either the latest native connection failure or framing failure.
If Idle gap produces several runs for one device message, increase message_gap_ms. If it waits too long after a complete message, decrease the value. If Line mode never starts a run, confirm that the device sends CR, LF, or CRLF. If the device sends no ending, use Idle gap. Raw mode can split one logical message into several runs because operating system chunks are not message boundaries.
An exceeded message limit means the device sent more than max_message_bytes without a valid boundary. BaudBound discards that oversized message and resumes at the next idle gap or line ending. Increase the limit only after confirming that the larger message is expected.
On Linux, inspect ownership with ls -l /dev/ttyUSB0 or the real device path and confirm the runner account belongs to the required group.
Confirm the family toggle, bind address, port, route, token status, allowed browser origin, and size limits. Use baudbound trigger-auth list SCRIPT or the desktop Security view to inspect token protection without exposing the token. Generate a replacement for a lost token and update the client with the new value. Use Doctor to confirm that the trigger is registered and healthy.
A Webhook 401 response means the token is missing. A 403 response means the token is invalid or the browser Origin is not allowed. A 503 response means authentication storage or the run executor is temporarily unavailable. WebSocket clients receive the equivalent error during the opening handshake.
Loopback accepts only local clients. A public bind is refused when a matching trigger has authentication disabled unless the unsafe override is enabled. It can still be blocked by the firewall or reverse proxy. A port conflict means another process, including a second BaudBound service, already owns it.
Use Webhooks, WebSockets, and Network Access for local request tests and exposure guidance.
Open the Security page and check whether BaudBound reports that encrypted secret storage is unavailable.
BaudBound connects to the credential vault in the background. A slow or broken credential service does not delay the desktop window from opening. Secret actions remain unavailable while the Security page displays Connecting.
On Linux, check Secret Service from the same terminal and graphical session used to launch BaudBound:
busctl --user list | grep org.freedesktop.secrets
A process ID means the service is running. A result containing only activatable means the provider is installed but did not start.
Test the provider independently from BaudBound:
printf 'baudbound-test' | secret-tool store --label='BaudBound test' application baudbound-test
Remove the test value after a successful check:
secret-tool clear application baudbound-test
If the storage command fails, repair the desktop credential service before troubleshooting BaudBound. If it succeeds, return to the Security page and select Retry. The page updates automatically when the connection attempt finishes.
VNC and other remote desktop sessions may require their own credential service startup configuration. Follow Linux encrypted secret storage for installation and verification instructions.
Log the resolved path or executable identifier without logging credentials. Check the runner account's permissions and working environment. Desktop-only actions require an active desktop target/session. Windows-title lookup modes are Windows Desktop-only. Use process-name or PID modes where documented on Linux.
HTTP Response, File Download, and File Read fail before returning oversized data. Check the three values under [limits]. An oversized download is removed before it can replace an existing destination file.
Check system time, HTTPS access to the GitHub release endpoint, availability of the correct artifact, and updater metadata. An AppImage must remain writable by its owner. Debian and RPM installations must be updated through APT or DNF and never through the AppImage updater. Do not bypass signature or checksum verification. Use the matching recovery steps from Installation and Updates.
Include the runner version, operating system, target runtime, command or UI action, script ID/name, run ID, trigger/node ID, and exact redacted error. Include relevant baudbound doctor --json, baudbound status --json, or baudbound script inspect SCRIPT --json output only after removing usernames, private paths, network tokens, serial numbers, and other sensitive values.
Do not attach .bbs packages, runner.db, config.toml, environment files, or secret keys to a public report unless you have inspected and intentionally sanitized them.
For backups and database-level recovery boundaries, continue with Storage, Backups, and Recovery.