Skip to main content

Error messages

Search this page with the exact message. Text in braces varies by installation.

Startup and configuration​

another Jiandu process is already using this installation​

Jiandu found the installation lock already held. Confirm whether another service, container, terminal, or restore tool owns the same data directory/database/blob namespace. Stop the duplicate cleanly. Do not delete a lock while a process is active.

the installation state directory is unsafe​

The data directory, a parent boundary, or sensitive file has unsafe ownership, permissions, or file type. Make it a real private directory owned by the Jiandu service account; reject symlinks and group/other-writable state. Re-run --check-config as that account.

configuration file {path} could not be read: {source}​

The configured file is missing, unreadable, or not a regular permitted file. Check the path inside the actual container/service environment and the service account's read access.

configuration file {path} is invalid: {source}​

The JSON is malformed or violates the closed schema. Use the line/field detail in {source}, compare with the version-matched example, and validate again. Unknown keys are errors.

configuration schema version {0} is unsupported​

The configuration targets a schema the running binary does not understand. Use docs and examples from that binary's release; do not simply change the number without reviewing changed fields.

invalid configuration: {0}​

The syntax was accepted but the combined values violate a deployment rule or bound. Read the detail after the colon. Common causes are an incomplete HTTPS ingress boundary, mismatched database fields, broad capture paths, or missing secret references.

environment variable {0} has an invalid value​

The named override cannot be parsed or is out of bounds. Remember that the service manager/container may inject a value not present in your interactive shell. Correct or remove it, then run --check-config in the service environment.

unknown command-line argument {0}​

The running version does not recognize the option, or an option intended for a wrapper was passed to Jiandu. Compare with Command-line tools. With scripts/run.sh, put server options after --.

missing value for command-line argument {0}​

The option requires a following value. Quote paths or origins that contain shell-sensitive characters and confirm the service definition did not split the value.

{0} uses plaintext OTLP to a non-loopback endpoint without explicit opt-in​

The telemetry exporter would send over plaintext beyond the local machine. Prefer an HTTPS collector endpoint. Use the insecure override only for a deliberate, protected test network after reviewing the exposure.

Backup, restore, and migration​

the destination must be an explicit path that does not exist​

Choose a new absolute destination. Jiandu will not merge with, clean, or overwrite an existing path. Inspect the existing destination separately before deciding whether it can be archived.

the restore target database must be empty and unpublished​

Provision a fresh database that no Jiandu process or other service uses. Do not point restore at a previous attempt or a live database.

the target database was restored but remains explicitly unpublished; use a new empty target for the next restore attempt​

The cross-system restore did not reach safe publication. Never start Jiandu against that target and do not retry into it. Preserve diagnostics, dispose of it using your database procedure, and retry with another new empty database.

a required database portability tool is unavailable​

Install the PostgreSQL 17 or 18 client tool matching the server/archive major, or set the documented absolute pg_dump/pg_restore path. Run the command as the same service account so PATH and permissions match.

the database portability tool version is incompatible​

Use a client whose major version matches the supported PostgreSQL server/archive major. Do not force a mismatched tool past preflight.

an archive file failed integrity verification​

The file length or checksum differs from the manifest. Stop using that copy, keep it unchanged for investigation, and try another verified backup. Checksums detect corruption; they do not repair it.

Capture and connectors​

the capture-agent state is unavailable​

The agent cannot read or safely use its state file. Check the configured path, persistent mount, ownership, and owner-only permissions. If the state was lost, revoke and re-enroll the agent.

the capture server is unavailable​

The agent could not reach the configured HTTPS origin. Check DNS, certificate trust, proxy availability, and outbound network policy from the agent host.

the capture server returned an invalid response​

The reached server did not speak the expected capture protocol. Confirm the URL points to the matching Jiandu installation and that an intermediary is not replacing API responses with an HTML error or sign-in page.

SANE scanimage is unavailable or the scan failed​

Install/locate scanimage, verify the service account can list and operate the device, and run a non-sensitive test scan directly on the agent host. Then retry through Jiandu.

the connector secret key file is missing, unreadable, or not owner-only​

Mount the configured file at the expected service path and restrict it to the service owner. Do not loosen permissions broadly to make startup pass.

the connector secret key file does not contain a base64 32-byte key​

Generate exactly 32 random bytes and store their base64 representation in the protected file. Rotating this key affects stored connector secrets; follow the connector recovery procedure rather than replacing it casually.

Still stuck?​

Record the Jiandu version, exact message, timestamp, affected action, and whether the failure survives a configuration-only validation. Redact credentials and document content. Follow the troubleshooting method before changing data.