Troubleshooting

Locate failures across connection, deployment, preparation, and execution.

Start with the failing stage. A successful local validation proves document shape, not server access, Action availability, or external service permissions.

Symptom	Check
Certificate verification fails	Server hostname, system trust, and `tls.ca_file`; see configuration.
Login fails or a request is unauthorized	Server URL, account status, and session/token validity. Log in again when the session expires.
Permission denied	Your Environment-scoped role; starting, deploying, approving, and administering require different permissions.
Action cannot be resolved during deployment	Registry host, repository prefix, credentials, exact Action version, and target platform.
Deployment revision conflict	Read the latest revision and review the intervening change before redeploying.
Preparation blocks	Missing context/secrets, incompatible input types, invalid references, or missing outputs from a skipped step.
Run waits for approval	Review the prepared step and obtain eligible approvals under all applicable policies.
Run remains queued	Read its diagnostic; check Environment occupancy, runner admission/connectivity, capacity, and image startup.
Action blocks after starting	Inspect attempt outcome, exit code, errors, external permissions, and non-private logs.
Logs or outputs are absent	Check whether the step is private, execution started, and logs reached their storage bounds.
Run becomes uncertain	Restore the owning runner and let it reconcile; see recovery.

Collect useful evidence

Terminal

pyplines --json run info 42
pyplines --json run attempts 42
pyplines --json run history 42

Include the platform/tooling versions, Environment, Pypline revision, Run ID, step name, and invocation ID when escalating an issue. Inspect outputs before sharing them; ordinary parameters and logs can still contain operational details.

For deployment failures, preserve the Definition and the full error. For runner issues, an administrator should also inspect pyplines runner list and the owning runner's service logs. Avoid modifying server state or discarding runner state to make a diagnostic disappear.

Recover or cancel execution

Make explicit recovery decisions while retaining prior attempts.

Find and use Actions

Select reusable operations available to your installation.