Troubleshooting and support

01 · Start with the last observed fact

This guide helps an operator choose the next useful check. Start with the surface, target, version and failed step. Separate a connection failure, an expected permission denial, an unavailable feature and a failed execution before making a change.

1. Identify the surface
2. Read the current state
3. Choose one bounded action
4. Check the result again

These are source-derived operating references and diagnostic reasoning examples. R4 added source-derived references. R5 adds explicitly labelled native screen observations and one read-only local health query; no customer end-to-end run was completed. The r232 first-customer administrator gap still blocks dependent actions; diagnostic guidance does not supply an alternative administrator.

Choose the finish line before investigating

Use one sentence: “I need to read the health of the supplied installation”, “I need the result of my submitted Work”, or “I need to verify the last administrator action”. Finish when that specific observation is available and understood. If a required delivery item is missing, finish the diagnostic record with its exact name and recipient; leave the operating task open.

For the examples below, “installation operator” means the customer role responsible for the installed service; “product administrator” means a person with an existing product grant; “delivery contact” means the supplier contact responsible for the version-specific installation handoff. Your organization may assign these roles to the same person. Record actual names in your private operating record.

For the full start-to-finish route and the right owner at each step, use Usage workflows. R6 adds explanatory procedures and an unbound Administration image; it performs no new product execution.

02 · Recognize two observed unavailable states

Actual native capture · 4 October 2026. MacBook, macOS 27.0.1 (Apple silicon), Packr bundle 0.99.0, local R234 launch/render candidate. The GUI source is revision 4ba82ca13946. These are real application windows captured through Computer-use. This candidate is not the frozen r232 appliance or a verified customer desktop delivery. The captured session had no available Control Plane connection. Images are unchanged; click one to inspect its original size.

Case A — Control Plane is not connected

Observed: the native status panel reports CONTROL_PLANE_UNAVAILABLE. A separate read-only local CLI health query returned exit 3, error PACKR_OPERATOR_STATUS_UNAVAILABLE and “Connection refused”. This narrows the observation to an unavailable endpoint at that moment; it does not diagnose installation, permissions or service ownership.

Next action: give the installation operator the supplied endpoint reference, version and exact error through the appropriate private channel. Preserve the failed observation. Do not infer successful preparation, retry submission or restart an unknown installation.

Case B — Pack projection is unavailable

Observed: the library reports PACKTORY_DOWNLOAD_SANDBOX_NOT_CONFIGURED and Download is disabled. Next action: ask the delivery contact to verify the intended Packtory context. Zero visible items while projection is unavailable do not establish loss of stored data.

These screenshots are current capture observations. The numbered reasoning examples later in this guide retain their separately labelled source-derived or fictional scope.

03 · Choose the right layer

Find the right owner with one useful request

04 · A running VM is not yet a ready product

Symptom: SSH works, but the planned operation cannot proceed. First use the supplied appliance health procedure. Then inspect the Headless status and health references for the delivered command and connection prerequisites.

1. Record whether the tool was available and whether it returned a result. Command-not-found, connection failure and an explicit unhealthy result are different observations.
2. Read the reported state and any unavailable or unevaluated fields. Keep the base-health result separate from first-administrator access, entitlement, runtime and storage readiness.
3. If a prerequisite remains unestablished, resolve that prerequisite with its owner. Avoid repeated restarts as a general cure.
4. After the authorized correction, repeat only the relevant read checks and compare with the earlier observation.

Worked reasoning example: a successful base-health check together with customer_operation_authority=NOT_EVALUATED means the check did not evaluate permission for customer work. Retain both facts and continue to the administrator/readiness checks; do not rename this result “ready to run AI”. This explains the retained health fields, not a new live result.

See Headless operation and the base-health checkpoint.

Case 1 — the command is not available

In the same terminal session, check the installed command location:

command -v packrctl

A returned path tells you which command this shell will use; compare it with the delivery record. No path means this shell cannot find it. Ask the installation operator to confirm the supplied executable and environment before continuing. Do not treat that result as a service failure. Completion: the supplied packrctl --help works and its supported commands match the intended delivery.

Case 2 — a health check fails

Run the observations separately:

packrctl status --json
packrctl health --json

05 · Desktop connection, empty screens and target mismatch

1. Confirm which window you opened: the Work client, VibePackr administration or Packtory Administration. Their connection and query routes differ.
2. Read the current client mode and target. In a remote administrative session, compare the displayed organization/appliance/installation with the intended target before making a change.
3. Use the documented refresh or query control. A visible menu, saved endpoint or an old projection is not a fresh connection result.
4. If connection fails, retain the sanitized error and have the connection owner verify the supplied endpoint and approved profile. Keep certificate and trust validation enabled.
5. If the target is wrong or unknown, stop changes, select the supported intended connection and re-check the returned identity.

Completion check: the expected target and fresh state are visible in the correct surface. This verifies the connection/read step only. For screen labels and mode-specific behavior use PackrGUI and VibePackr Admin.

Case 3 — an empty client or a disabled Submit

06 · Work accepted, denied, incomplete or unexpected

1. Keep the returned Work/operation reference. Query that same item before creating another request.
2. Read the status and reason fields, then any execution, validation, evidence and receipt records actually returned. Empty, unavailable and pending fields must remain distinct.
3. Check the supported operation and input of the route you used. A GUI control can prepare a draft without proving that a selected Pack or attachment is consumed by the execution route.
4. For a denial, resolve the stated input or permission condition through its owner. For an uncertain response, perform read-only reconciliation before any resubmission.
5. After an authorized next action, inspect the same item and compare the actual outcome with the intended task. A process exit or receipt alone does not establish business acceptance.

Worked reasoning example: a request is submitted and the connection drops before the result appears. Record “response uncertain”, reopen the read view and look for the original reference. Creating a new request immediately could duplicate work; a timeout does not tell you whether the original change occurred.

Use the exact result shape described in Headless or the specific local/remote path in PackrGUI. Do not combine result fields from different routes into an invented success record.

Case 4 — find the submitted item before making another

packrctl work list --limit 10 --json
packrctl work show WORK_ID --json

1. Use the same installation and local principal as the original submission. Replace WORK_ID with the returned identifier, not the intent text or idempotency key.
2. If the Work is outside the first ten recent entries, increase the list limit within the documented maximum of 100. A missing item still requires scope/identifier reconciliation; it is not permission to recreate it.
3. When found, compare work, reports and selected_report. Use the Headless result interpretation for that route; retain any missing fields as missing.
4. If the result is denied, preserve the specific reason and correct only its input/access prerequisite. If it is partial or failed, record the reported effect before recovery. If human acceptance is pending, assign the authorized reviewer.
5. If no identifier was received, retain the original key, time and non-confidential task description privately and ask the installation operator to reconcile the original submission. Avoid searching another user's scope or issuing a new key.

Close this investigation when the same Work's current result and remaining action are known. Close the operating task only when its required result, validation and human decision are actually satisfied.

07 · Administrative revision, session and result problems

These tokens describe the inspected administrative paths; use the actual token returned by your version. The Admin guide explains exact surfaces and request prerequisites. No key replacement, role expansion or bootstrap workaround is prescribed here.

Case 5 — a revision changed while you were reviewing

Illustrative sequence: you reviewed appliance state revision 12, but the service now reports appliance state revision 13. The request’s expected revision tracks this appliance state revision, which is separate from the configuration revision. On STALE_REVISION, select Overview → Refresh, compare the current state with the intended change and consult the recorded audit transition. If the recorded action result, audit reference and available current observations establish that the same change was already applied, record that finding instead of issuing it again. A revision number alone cannot establish the value; the general configuration projection withholds values. If still needed, review a request against the newly observed state. Revision numbers here are fictional; do not copy them into a request.

Case 6 — restart timed out

1. Keep the pending operation and literal REMOTE_ADMIN_OPERATION_TIMEOUT_UNCERTAIN reason.
2. Use Backup/Recovery → Reconcile exact request for that pending request. Then refresh the appliance view.
3. Compare Active, Process alive and Product ready, and inspect the action result/audit reference. Product authorization alone is not evidence that the host action ran.
4. If the process is active but product readiness remains false, run Diagnostics → Run diagnostics and take the Headless health branch. Escalate the affected component, retaining the original operation reference.

Completion: the original action’s effect is reconciled and product readiness is checked. If reconciliation cannot establish the effect, keep “uncertain” and request operator/support review of that exact request; do not schedule another restart.

08 · Packtory: a blank panel is not a storage-loss diagnosis

1. Check whether you are reading local Headless Packtory status or the separate Packtory Administration dialog.
2. In the dialog, identify the selected tab and its source. A management authority/context query does not itself populate every asset, lifecycle or audit view.
3. Compare an unavailable action with the documented surface limit. An unavailable UI action does not establish absence of canonical backup/recovery machinery.
4. For a suspected storage problem, retain the exact status, target and last successful observation. Verify the resource/connection with its owner before initialization, deletion or restore.
5. For Contribution, inspect preview/export/verification results as the separate flow documented in the Packtory guide. Do not infer that a local export was remotely uploaded.

Completion check: either the intended supported query returns the expected view, or the exact unavailable route is identified without changing storage. Product backup/recovery, fresh-target restore and production object-storage connection have separate authority and proof conditions.

Continue with Packtory Admin. Remote Rescue transport remains disabled; the separate future Rescue-to-Packtory adapter is not the existing local Packtory Administration surface.

Case 7 — Assets is empty while management says AUTHORIZED

Return to the correct task

For search, filters, disabled draft selection or partly denied download, use the library failure table. For Binding required, compare the actual unbound Overview and ask the domain owner for the supported binding. AUTHORIZED and zero counters do not prove a connected inventory. Conditional download/derivative controls in the inspected client use supplied sandbox configurations; do not turn missing setup into a customer repair recipe.

09 · Helper and AI failures have their own next checks

Use the existing specific error references instead of changing unrelated appliance settings.

• Document parsing, required properties, unsupported fields or MCP revision: compare the exact input with the Helper error examples, fix only the stated input mismatch and re-check through the supported path.
• Target Contract or binding: distinguish source-document acceptance from target validation and registration in the Developer Guide.
• AI authentication, permission, model/location, rate limit or timeout: use Agents & AI. Preserve the exact stage and response before changing provider configuration.
• Agent-generated instructions: verify fields and commands against the supplied documentation. An assistant explanation does not establish that the product ran a tool or connected to a provider.

Case 8 — separate input correction from service repair

If Helper identifies a missing required property or unsupported field, keep the same source document, correct that specific declaration and repeat the supported check described in the error examples. Do not change appliance permissions to fix a document-shape error. If parsing succeeds but target binding is not established, retain the accepted input and resolve that binding separately. For provider failures, record the stage and literal status before interpreting it; a model/location or quota problem is not evidence that a Work receipt or administrator grant is missing.

10 · Keep a before/action/after record

Use this worksheet for one operating task. It helps another operator understand what happened without receiving unrestricted logs. A read-only diagnostic task can end with a clear limitation and named next owner; it does not need a successful mutation to be useful.

One operating task — documentation worksheet
Goal: [one intended outcome]
Surface / version / target: [confirmed scope]
Mode: [read-only / authorized change]
Prerequisites: [access, readiness and supported inputs]
Before: [state and revision, where reported]
Action: [one supported command or UI operation]
Returned: [status, reason and operation/work reference]
After: [fresh read-only observation]
Expected versus observed: [match / mismatch / uncertain]
Validation and result review: [specific observation]
Next step and owner: [bounded next action]
Do not mark success from process exit, a visible menu, an accepted request or a timeout alone.

For a change, record the current revision if supplied, the intended effect, the returned state and a fresh read after the action. If the result remains uncertain, say so explicitly and preserve the original reference.

A filled record you can compare with your own

The following fictional case closes an input-syntax problem. It does not report a product test. Notice that the original failing invocation and the later observation remain separate.

ILLUSTRATIVE FILLED RECORD — NOT AN EXECUTED PRODUCT TEST
Goal: Read appliance health in a structured form.
Surface / target: Headless; supplied installation alias DEMO-APPLIANCE-A.
Version: Record the actual delivered version before a real run.
Mode: Read-only.
Before: Invoked packrctl health --quiet --json together.
Observed branch: Invocation rejected because quiet and JSON cannot be combined.
Action: Choose packrctl health --json; make no service/configuration change.
Expected correction: The valid invocation returns a structured health result.
Result interpretation: Read readiness and its reason independently of syntax success.
Finish line: Syntax issue resolved when the accepted query returns the intended form.
If still non-ready: Open a separate component-readiness investigation.
Next owner: Operator for the read check; relevant component owner if non-ready.
This record does not claim that a particular installation was ready.

11 · Escalate with a small, usable support report

Send a focused report to the responsible product or cloud owner. The product support address is support@vibepackr.com. Use a subject such as “Headless health check — unexpected result” or “Packtory Administration — query does not populate Assets”. State what you observed, not an assumed root cause.

VibePackr support report — documentation worksheet
Surface: [Headless / PackrGUI / VibePackr Admin / Packtory Admin]
Product / client version: [reported version, or unknown]
Time and time zone: [observed time]
Target: [local or remote; use an approved non-secret reference]
Task and expected result: [one sentence]
Last successful step: [step]
Failed step: [exact command shape or screen action; remove private values]
Observed status / reason: [sanitized exact values]
Was a change submitted? [yes / no / uncertain]
Read-only reconciliation after failure: [observed state or not yet checked]
Customer impact: [what is unavailable]
Actions already taken: [facts, no speculation]
Question / requested next step: [one bounded request]
Exclude passwords, tokens, private keys, credential paths, raw logs and customer payloads.
Send extra identifiers or diagnostic packages only through the agreed private channel.

If a supported diagnostic package is requested, follow its preparation and sanitization checks in the Admin guide and the agreed private transfer channel. Package generation, permission to transmit and support entitlement are separate. No response-time promise is made in this guide.

Before closing: retain the agreed next action and owner, or confirm the original intended state through the relevant read check. Do not erase the first failure record when a later check succeeds.

Send the unanswered question, not an assumed diagnosis

When self-service ends at a missing delivery item, name it explicitly. This fictional request concerns the CSV retrieval handoff; it does not request a new feature or include private evidence.

ILLUSTRATIVE SUPPORT REQUEST — NOT A REAL INCIDENT
Subject: Packtory contribution export — artifact retrieval handoff needed
Surface: Packtory Administration / Contribution.
Client version: [enter supplied client version privately]
Target: DEMO-APPLIANCE-A (fictional customer-approved alias).
Task: Obtain the authorized CSV associated with one recorded export.
Last step: Reviewed the export manifest and verification result.
Observed issue: Export CSV did not create a browser download/save dialog.
Interpretation: The manual documents that this frontend does not save the file that way.
Requested next step: Please identify the supported retrieval method and authorized
recipient for this delivered version, tied to the exact Export ID and CSV digest.
Export reference: [provide the actual reference only through the agreed private channel]
Actions taken: No repeated export; no storage or permission changes.
Still open: Artifact retrieval and actual downloaded-file digest comparison.
Excluded: Credentials, evidence payloads, customer names and raw logs.