guardianMOBILE RELEASE ANALYSISGet early access
Menu
Documentation Troubleshooting · Menu
SUPPORT

Troubleshooting a Guardian scan

Organised by what you are seeing rather than by what is wrong, because you know the first and not yet the second. 15 entries.

By symptom

Entries

guardian: command not found

Likely causes

  • The CLI is not installed on this machine or in this shell’s PATH.
  • It was installed for a different user, shell or Python environment.
  • You are in a CI runner where the installation step has not run.

Diagnose

  • Run `guardian version` in the shell where you expect it to work.
  • Check whether the shell that failed has a different PATH than your interactive shell.

Resolve

  • A public installation route has not been published yet, so there is no command here to copy. If you already have the CLI, invoke it by its full path to confirm the binary itself works before investigating PATH.
  • In CI, the installation step is the marked placeholder in the templates. A pipeline cannot find a tool nothing installed.

Do not install from an unofficial mirror. There is no published distribution channel to compare a mirror against.

Confirming an installed CLI

The project is not detected, or the wrong platform is reported

Likely causes

  • The path passed is a parent directory or a monorepo root rather than the application.
  • Project manifests are missing, renamed or generated at build time.
  • The application uses a structure Guardian does not recognise yet.

Diagnose

  • Run `guardian detect .` from the directory you believe is the project root and read what it reports.
  • Confirm the platform manifests are present in a fresh checkout, not only after a build.

Resolve

  • Point Guardian at the specific application directory rather than a repository root containing several apps.
  • If manifests are generated, run whatever generates them before scanning.

Detection output describes your project structure. Treat it like any other project detail when pasting it into a ticket.

How detection works

The project structure is reported as unsupported

Likely causes

  • The project is not Flutter, native iOS or native Android.
  • A supported platform is present but nested somewhere detection does not reach.

Diagnose

  • Run `guardian detect .` and compare the result with the platform guides.

Resolve

  • Scan the supported sub-project directly.
  • Where no supported platform exists, Guardian is not the right tool for that repository, and reporting it as unsupported is the correct outcome.

An unsupported result is not a pass. Nothing was checked.

What Guardian supports

Permission denied while reading the project or writing a report

Likely causes

  • The output path is not writable by the user running the command.
  • Parts of the project are owned by another user, common after a build ran as root in a container.

Diagnose

  • Confirm the user running Guardian can read the project directory and write to the output path.
  • In a container, check whether a previous step changed ownership.

Resolve

  • Write the report somewhere the current user owns by passing an explicit path to `--output`.
  • Fix ownership on directories a build step changed, rather than running the scan with elevated privileges.

Do not run a scan as an administrator to work around a permissions problem. A read-only tool does not need write access to your source.

A local SDK or platform tool appears to be missing

Likely causes

  • The machine has the project but not the platform toolchain the project expects.
  • A CI image is minimal and does not include the mobile SDKs.

Diagnose

  • Run `guardian doctor` to inspect the local Guardian environment.
  • Read the coverage section of the report: checks that could not run are listed there rather than silently skipped.

Resolve

  • Install the toolchain the project needs, or accept the reduced coverage knowingly.
  • In CI, use an image that already contains the mobile toolchain.

Reduced coverage is reported, not hidden. Do not treat a scan with missing tooling as equivalent to a complete one.

How incomplete coverage is treated

The scan finishes but coverage is incomplete

Likely causes

  • An analyzer could not run because a prerequisite was absent.
  • Test results or other evidence were never supplied to the run.
  • The project structure excluded some analysis paths.

Diagnose

  • Read the coverage list in the report. It separates completed, incomplete and not-run.

Resolve

  • Supply the missing evidence, or record deliberately that you accept the gap.

Incomplete coverage never becomes a pass. That is the design, and working around it defeats the purpose of running the gate.

Coverage and the gate

The report is not generated, or is not where you expected

Likely causes

  • The output directory does not exist.
  • A relative path resolved against a different working directory than you assumed, which is common in CI.
  • The format and the output flag were combined in a way the installed build does not support.

Diagnose

  • Use an absolute path for `--output` while diagnosing.
  • Run `guardian scan --help` on your installed build to confirm how that build treats `--output` alongside each format.

Resolve

  • Create the output directory before the scan runs.
  • Generate one format at a time until you have confirmed the behaviour of your installed version.

The bundled help describes `--output` in terms of a JSON report. Confirm behaviour for other formats against your own build rather than assuming.

Report formats

The HTML report will not open, or looks wrong

Likely causes

  • The file was moved away from assets it expects to sit beside.
  • A browser or viewer is blocking local file access.

Diagnose

  • Open the file directly in a browser from its original location.

Resolve

  • Keep the report in the directory it was written to, and move the whole directory if you need to relocate it.

An HTML report can contain project paths. Opening it is local; sending it is a disclosure decision.

The baseline cannot be read

Likely causes

  • The baseline path is wrong, or the file was never committed.
  • The baseline came from a different project.
  • The file was produced by a version whose format differs from the installed one.

Diagnose

  • Confirm the file exists at the path passed to `--baseline`, from the working directory the command actually runs in.

Resolve

  • Commit the baseline alongside the project so CI and local runs use the same file.
  • Regenerate the baseline with the version you are running, and review what that accepts before committing it.

Regenerating a baseline silently accepts every current finding. Treat it as a reviewed decision, never as a fix.

Working with baselines

CI cannot locate Guardian

Likely causes

  • The installation placeholder in the template was never replaced.
  • Guardian was installed in one job and used in another without sharing the environment.

Diagnose

  • Print the PATH in the failing step and confirm the installation step ran in the same job.

Resolve

  • Install and use Guardian within a single job, or share the installation explicitly through your CI’s caching or artefact mechanism.

Do not add a token or credential to make an installation step work. If a step needs a secret, it is not the documented path.

CI/CD templates

The release gate behaves unexpectedly in CI

Likely causes

  • The pipeline is reacting to the wrong exit status.
  • A baseline is present locally but not in CI, so the run compares against nothing.
  • The policy differs between the two environments.

Diagnose

  • Run the same command locally and in CI and compare the reports rather than only the exit status.
  • Confirm the baseline file is committed and reachable from the CI working directory.

Resolve

  • Commit the baseline and the policy configuration so both environments evaluate the same inputs.
  • Test your pipeline’s reaction to a deliberately failing run before relying on the gate.

Exact exit behaviour for every policy outcome has not been independently verified in this repository. Invalid input was observed returning exit code 2. Verify the codes your pipeline depends on against your own build.

Blocking conditions

Dynamic analysis prerequisites are missing

Likely causes

  • No device, emulator or simulator is available to the run.
  • The command group has prerequisites that are not documented yet.

Diagnose

  • Run `--help` on the dynamic-analysis command group against your installed build.

Resolve

  • Treat dynamic analysis as exploratory and run it manually rather than in a pipeline.

Dynamic analysis is not production-ready. Never make a release decision depend on it, and only ever run it against an application and environment you are authorised to test.

Dynamic analysis status

A scan is slow on a large repository

Likely causes

  • The path passed includes build output, caches or vendored dependencies.
  • A monorepo root was scanned instead of one application.

Diagnose

  • Time a scan of a single application directory and compare it with the repository root.

Resolve

  • Scan the application directory rather than the repository root.
  • Exclude generated and vendored directories from the scanned path where your configuration supports it.

No performance figures are published for Guardian, and none should be inferred from a single run on one machine.

Results differ when the machine is offline

Likely causes

  • Checks that depend on external data are limited to whatever is available locally.

Diagnose

  • Compare the coverage section of an online and an offline run.

Resolve

  • Refresh any local data those checks depend on while connected, then scan offline.

Local analysis completes without a network connection. Anything derived from external data is only as fresh as your local copy, and the report should be read with that in mind.

Offline behaviour

A finding looks wrong

Likely causes

  • The check is correct but the context makes it acceptable.
  • The check is genuinely wrong for this project shape.

Diagnose

  • Read the check’s entry in the catalogue: each one lists the situations where it can be wrong.
  • Confirm the evidence the finding cites actually matches your project.

Resolve

  • Where a finding is acceptable in context, record the decision — a baseline is the supported way to carry accepted findings forward today.
  • Where a check is genuinely wrong, note the project shape that produced it; that is the information that improves the check.

Do not accept a finding into a baseline without reading it. A baseline is a record of decisions, not a mute button.

Per-check false-positive notes