TIENDocumentation
Docs/Help

Troubleshooting

A repository engine is missing

In hybrid mode, Tien tries the local command and then Docker. Confirm that Docker is running, or install Gitleaks, OSV-Scanner, and Semgrep in PATH.

Use cli mode when you want missing local tools to fail immediately. Use docker mode when you want consistent containerized execution.

The URL scan says authorization is missing or expired

Create a fresh grant and publish the exact value shown by Tien:

tien authorize dns --domain app.example.com --valid-for 24h

Confirm the absolute _tien-authorization.<host>. TXT name, exact hostname, url-scan scope, 256-bit challenge, timestamps, and operator max_validity_minutes. DNS propagation can delay verification. For a multi-host batch, generate every host in one command with repeated --domain flags. DNS TXT is the only supported authorization method; legacy http and dns+http configs must be changed to method: dns.

The grant must remain valid for the full run. If the earliest grant expires during execution, Tien aborts with authorization failure. MCP reports a tool error and does not return the scan as a partial success; issue and publish a new grant before retrying.

Legacy raw tien=<token> records and require_ownership_proof: false are not accepted. Generate a structured grant and use explicit local/private development exemptions only for environments the operator controls.

Do not add localhost or private-network exemptions to scan a public third-party target.

An authorized hostname resolves to a blocked IP

Tien blocks loopback, private, link-local, CGNAT, multicast, unspecified, and metadata addresses by default to prevent DNS rebinding and SSRF. Use a literal localhost/private target with an explicit development exemption. For a hostname that intentionally resolves to RFC 1918 or IPv6 ULA space, add that exact hostname to allow_resolved_private_hosts, use an https:// target, set method: dns, and publish its exact structured DNS TXT grant. Tien pins the resolved addresses for the run. This allowlist does not permit wildcards, loopback, link-local, CGNAT, multicast, unspecified, or metadata addresses.

The legacy global key allow_resolved_private_ips is rejected. Replace it with the exact-host allowlist; do not use migration as a reason to broaden network scope.

An explicitly selected config file is missing

When --config <path> is provided, Tien treats that exact file as required. A missing, unreadable, or invalid file fails the command or MCP startup; it does not fall back to the default path or built-in defaults. Correct the path, permissions, or YAML before retrying.

A piped report cannot read JSONL

Stdin uses the configured default format. Set the input format explicitly:

tien scan repo --path . --format jsonl \
  | tien report --input-format jsonl --type text

Files are normally detected by content or extension.

CI reports a failure after writing the artifact

Check the exit code. Code 3 means the scan completed but the policy threshold was met. Code 1 means a runtime or scan error. Tien writes available findings before returning a policy result.

The scan is slow

  • Keep dependency and build folders in repo.exclude.
  • Leave repo caching enabled.
  • Reduce unnecessary Semgrep rules.
  • Use deterministic shards for large URL lists.
  • Tune resource budgets based on the environment instead of dropping authorization checks.

Findings contain expected test fixtures

Confirm the fixture cannot ship or expose a usable secret. Then add the narrowest justified exclusion or engine-specific suppression and document why it is safe.

A finding disappeared without a code change

Check scanner versions, rules, advisory data, configuration, exclusions, cache state, and target scope. For reproducible CI, pin Tien, external engines, images, and rules.

The HTML report does not open automatically

tien plot writes HTML to stdout. Save it first:

tien plot result.tien > report.html

Then open the file with your browser.

Interrupted scan

On Ctrl+C, Tien attempts to write partial findings and exits with code 130. Treat the artifact as incomplete and do not use it as a release baseline.

Getting more detail

Run the relevant built-in help and confirm the effective config:

tien scan repo --help
tien scan url --help
tien report --help

If the problem is reproducible, open an issue with the Tien version, operating system, command, sanitized config, and redacted error output. Use a private security advisory for sensitive vulnerabilities.