Troubleshooting

The scenario Inspector reports an error

Use a stable scenario ID containing only letters, digits, periods, underscores, or hyphens. Select a .unity scene under Assets, a valid target/build/timing policy, at least one known metric, valid repetition/cooldown/timeout values, and valid environment requirements. Custom marker IDs/names, loading transitions, and extension provider selections must be unique and valid.

The Run Center rejects my profile

For local desktop execution, use standalone macOS, Windows, or Linux with a valid transport. Required PlayerConnection needs a Development Player. For Android, iOS, or WebGL, use the Run Center external-device workflow to build an External Capture Kit and import its exact portable-bundle inventory.

A metric is unsupported, unavailable, permission-denied, or invalid

Do not convert the state into zero or a pass. Unity counters vary by player build, platform, graphics API, hardware, and runtime configuration. Review the capability detail, confirm the metric was enabled in the scenario, and repeat on the intended player/device. For an extension metric, also verify that the selected stable ID/unit matches a registered provider and that the provider returns finite values.

The capture fails an environment requirement

The measured operating system, platform, device, graphics identity/API, build type, memory, or exact fingerprint does not satisfy the scenario policy. This is an evidence failure by design. Run the candidate on the reviewed environment or change the scenario policy only after reviewing why the environments should be comparable.

Baseline comparison reports an environment mismatch

The baseline and candidate fingerprints differ or one is missing. Recreate the candidate under the reviewed baseline environment. Disabling comparison-level environment matching is an explicit reviewed choice and does not bypass missing or invalid capture evidence.

CI reports EvidenceInvalid or EnvironmentMismatch

Inspect every candidate, capability, environment, baseline, and budget evaluation. Missing baselines, metrics, fingerprints, units, scenarios, unsupported capabilities, malformed bundles, or invalid budgets are evidence errors rather than performance passes. Preserve the generated evidence directory on failed CI jobs.

Evidence export refuses the destination

Use an owned child output directory rather than a filesystem, home, project, Assets, Packages, Library, or Temp root. Performance Lab rejects unsafe links/reparse points and foreign output state rather than deleting it.

A desktop player result never arrives

Preserve the player log and process exit code. Confirm the selected transport is available, the result destination is writable, the measured environment satisfies the scenario, and the selected counters can run in that player. For loading transitions, confirm the exact target scene is loadable and the timeout was not exceeded. For custom markers, confirm the exact configured ProfilerMarker name executes during the sample window.

An external-device capture is incomplete

Use the exact player bytes from the generated capture kit. Do not rebuild between repetitions. The queue advances only after the current bundle publishes successfully. Collect exactly the .kplab filenames listed by the kit manifest; missing or additional bundle files fail import. On WebGL, press the in-player download button for each bundle before continuing.

An interrupted run appears after restarting Unity

Performance Lab intentionally does not resume a benchmark mid-state. Use Tools > Kiwi Studios > Performance Lab > Recovery > Reveal Interrupted Evidence to inspect preserved evidence. Use Retry Interrupted Run as New Run to start a new reviewed run from the bound profile.

A repeated, A/B, or A-B-B-A comparison is invalid

Confirm every measurement has a unique stable ID and canonical source hash, uses the intended scenario and comparable environment, and contains replayable raw evidence. A-B-B-A requires complete contiguous A, B, B, A blocks; missing, duplicated, overlapping, or reordered runs fail closed.

BuildReport evidence is unavailable or invalid

Pass the completed non-null BuildReport returned by the same build invocation. Confirm the summary succeeded, timestamps are canonical and chronological, output/inventory paths are portable and link-free, and required size/duration evidence exists. Build duration remains diagnostic unless separately benchmarked under controlled conditions.

Build comparison reports an environment mismatch

The candidate and reviewed baseline differ in Unity version, operating system, processor, memory, batch-mode state, target, target group, subtarget, or build options. Repeat the build under the reviewed environment or document an explicit comparison policy; do not bypass missing or invalid host evidence.