Troubleshooting

Start with the symptom below. For request failures, inspect Response → Network for connection details and Results for script, capture, assertion, or test errors.

I cannot edit or send a request

A directory with no .environments/, settings.yml, or root request .yml file opens in read-only browse or empty mode. Press Ctrl+P and choose Initialize Collection, or initialize the existing directory from the CLI:

noodle collection init ./my-api
noodle ./my-api

If the path is missing or not a directory, correct it first. Bare noodle opens the first existing registered collection, falling back to the current directory. Use an explicit path when a different collection opens than you expected.

A variable or secret is unresolved

Check the selected environment, key spelling and case, enabled state, and saved edits in F3. CLI runs use --env or the collection’s saved default. A secret needs both an enabled declaration and a value from its process environment or OS vault. Inspect names and resolution status without printing values:

noodle secret list --env staging --collection ./my-api

A non-secret environment value does not automatically come from the shell. See Environments and secrets for setup.

A request fails before a response

Symptom	Check next
DNS or unreachable-host error	Confirm the resolved URL, hostname, VPN, and network access. Check the selected environment.
Connection refused	Confirm the API server is listening on the URL’s host and port.
Timeout	Check the server and network, then the request’s timeout setting. A larger timeout will not fix a wrong host.
Proxy connection or authentication error	Check global and collection proxy mode, bypass rules, and saved proxy credentials.
Certificate verification failure	Confirm the hostname, certificate expiry, and trusted CA bundle. A custom CA bundle replaces default roots.
Client certificate failure	Check the exact destination host/port, PEM certificate and key paths, and stored passphrase.

Use Proxies and TLS for network configuration. The Network tab also shows OAuth token acquisition, redirects, and handshake events. For an HTTP 401 or 403, the server did respond: check Authentication and the selected credential source.

A capture, assertion, or script fails

Expand the failed row in Results. Check the actual response shape before changing the expression. JSON body paths require valid JSON and do not work on binary responses. Assertion equality is typed, so 200 differs from "200".

A transient capture is shared only within one collection run. If a second manual send cannot find it, use explicit persistence or run both requests together. See Captures and Response assertions. For script errors, check the source location and Script API limits. Pre/post support top-level await and request calls through noodle.runRequest and noodle.sendRequest. Await each call; overlapping calls and unfinished work fail the script. Raw fetch, imports, and timers remain unavailable.

CI or the Runner reports failure

HTTP status 400 or higher, failed captures, scripts, assertions, or tests can fail a request. Run commands use exit 1 for executed-request failures and 2 for pre-run configuration failures. Inspect data.result for a single request, or data.results and data.skipped for a collection’s JSON output.

If a tag filter selects nothing, check case and inherited folder tags. All include tags must match, and any exclude tag removes the request. Save TUI drafts before starting the Runner. See CLI automation and CI for failure reporting and a complete CI example.

A collection contains invalid YAML

Noodle opens a repair workspace for invalid request or folder files. Select the file, correct it using inline validation, and press Ctrl+S to save and reload. For a malformed settings.yml, correct the file before opening the collection. Validate from the CLI with noodle collection audit ./my-api.

collection format canonicalizes valid request files; it does not repair arbitrary malformed YAML. Audit --fix can rewrite supported fixable content, so review its reported changes before committing.

Cookie storage is unavailable or plaintext

cookies plaintext means the vault was unavailable and the jar uses a protected plaintext file. Fix the keyring access, restart Noodle, and check the warning. For other storage errors, open Cookies and retry with r after fixing the reported cause. Resetting unavailable storage from the jar view creates a backup; use it only if you intend to discard the current jar’s usable session state.

Linux and headless environments

On Linux, Noodle uses the Secret Service API through a provider such as GNOME Keyring or KWallet. A desktop session normally starts and unlocks the provider for you. On a headless server, you must provide a user D-Bus session and an unlocked keyring collection.

Install a provider and the command-line Secret Service tools first:

# Ubuntu/Debian
sudo apt install gnome-keyring libsecret-tools dbus-user-session

# Fedora
sudo dnf install gnome-keyring libsecret

# Arch
sudo pacman -S gnome-keyring libsecret

Run Noodle inside the same user D-Bus session as the keyring. If a foreground gnome-keyring-daemon --start process is already running, stop it with Ctrl+C first:

dbus-run-session -- bash
read -rsp "Keyring password: " KEYRING_PASSWORD
printf "\n"
eval "$(printf '%s\n' "$KEYRING_PASSWORD" | gnome-keyring-daemon --unlock --components=secrets)"
unset KEYRING_PASSWORD
noodle --collection ./my-api

The --unlock step creates or unlocks the login collection without requiring the graphical SystemPrompter. Keep Noodle in that shell; a separate SSH shell will not share its D-Bus session. For unattended jobs, provide the same-named secret through the process environment or use an external secret manager instead of depending on an interactively unlocked keyring.

Keyring error messages

• Object does not exist at path .../collection/login means the login keyring collection is missing or locked. Run the headless setup above.
• couldn't initialize prompt or SystemPrompter GTK warnings mean the keyring tried to open a graphical prompt. Use gnome-keyring-daemon --unlock with the password supplied on stdin.
• cookies plaintext means Noodle could not access the OS vault and used a mode-0600 fallback for the cookie jar. Restart Noodle after fixing the keyring.

An environment write is blocked by a lock

An environment mutation timeout identifies .environments/.mutation.lock. Do not remove it while another writer is active. After an interrupted writer, check that environment files and vault entries agree and confirm that no writer is running before manually removing the exact lock directory named in the error. Locks are never reclaimed just because they are old.

A binary response cannot be previewed or saved

Preview depends on the terminal’s image protocol and the supported image format. Images above 5 MiB require explicit activation. Use Save file for a live binary response when preview is unavailable. Binary history and Runner details retain metadata only, so resend the request to download its body.

CLI --output requires a new destination and fails before HTTP if it already exists. TUI Save As picks an available numbered filename. See Inspect and save responses.

Read a notification again

Press Ctrl+P and choose Show Last Notification to reopen the latest message, even after its toast disappears. Use ↑/↓, PgUp/PgDn, or Home/End to scroll and Escape to close. This is useful for multiline import warnings and errors in small terminals.