Rubian and Kestowv troubleshooting
Applies to: Provisioned Rubian and Kestowv environments
Updated
Start with the exact failing operation and the environment in which it ran. Retain its output before changing configuration. The same symptom can have different causes in a Rubian session, a pilot command and a public browser preview.
Rubian commands and files#
| Symptom | Check | Resolution |
|---|---|---|
| Unknown command or method | Spelling, Ruby syntax and the supplied build's command list. | Use the matching guide or obtain a build containing the required command. |
cd did not take you where expected |
Run pwd; read any message from cd. |
Use the intended full path and verify the location before continuing. |
| A listing is empty | Session, path and whether the directory is actually empty. | Distinguish an empty array from a failed host lookup returning nil. |
A file read returns nil |
Repeat the specific read without quiet: true and inspect the diagnostic. |
Correct the path or access problem. |
| A combined read is incomplete | Check each requested path separately. | Do not assume a successful combined return means every file was read. |
| A known file is missing from an inventory view | The last discovery time and whether the file lies within the scanned scope. | Try its explicit path, then use refresh(:local, deep: true) if the home inventory needs updating. |
| A familiar command behaves differently from another shell | The Rubian command's parameters and return contract. | Use its reference rather than assuming Unix flags or behavior. |
| A managed-file copy or deletion is unavailable | Whether the operation crosses host/managed storage or uses an unimplemented managed operation. | Follow the file-operation matrix. |
Libraries, processes and collaboration#
For a missing library function, inspect forge_list and the registration result before changing the library or Ruby environment. Registration can expose functions, classes, value extensions or no usable interface. See Forge compatibility.
If Taskman cannot open, check the supplied Tk and display requirements. The terminal inspection commands remain separate options. Confirm whether an identifier is a host PID, a Rubian job ID or an agent name before using a stop control.
If a workspace does not respond, compare availability, report age and requested versus applied service state. Reading an activity stream consumes pending messages, so an empty second read is not evidence of failure. If a project has been created before, resume it with proj_cd; invoking the creation command again can rewrite its starter files.
Background and recurring work#
When job_result returns nil, inspect bg(id) for state and error. A successful operation can return nil; unfinished, unknown and failed jobs can also have no result. If a caller's wait expired, the job may still be running. Inspect it before submitting another copy.
For recurring work, compare the tick count, last error and current job state. If work resumes unexpectedly, check whether its persistent definition remained enabled. daemon_stop(name) and daemon_stop(name, disable: true) have different restoration behavior.
If persistent status cannot be written, resolve authenticated-workspace access before relying on the next restart. Preserve the last successful result and the write error for support.
Pilot configuration and readiness#
| Reported problem | Action |
|---|---|
| Invalid JSON, unknown key or duplicate name | Correct the manifest and rerun validate. |
| Command supplied as a string | Replace it with an executable-and-arguments array. |
| Missing or unsafe secret reference | Provision the expected regular file with access limited to its owner. Do not move the secret into inline configuration. |
| Required resource control unavailable | Check host support and delegation with the environment administrator. Preserve the declared requirement. |
| Missing release source or version conflict | Verify the prepared package and choose a new version for changed contents. |
| Missing status or metrics | Check the manifest, state-directory override and whether the pilot has written state. |
| Workload name not found | Run workloads against the same manifest. |
Deployment or service failure#
An activation failure requires a check of the active release and its health result. A service that repeatedly fails requires inspection of its command, dependencies, credentials and application logs. Stop retrying an operation that may duplicate external effects.
After standalone rollback, follow the supplied restart or reprovisioning procedure and verify the running application. The selected release and a healthy application must both be confirmed. See Services, releases and recovery.
Report an issue#
Send a concise report through Valen Systems support: product and package version, host platform, failing command, expected behavior, actual result, timestamp and a short redacted error. Include the smallest configuration fragment that reproduces the issue. Remove credentials, customer data and unrelated activity; retain the full operational record in your authorized environment.