Skip to content

Say why something failed and what to do next - #87

Open
wrrfsub wants to merge 3 commits into
serveroshq:mainfrom
wrrfsub:issue-86
Open

wrrfsub wants to merge 3 commits into
serveroshq:mainfrom
wrrfsub:issue-86

Conversation

@wrrfsub

@wrrfsub wrrfsub commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

When something goes wrong, the panel now says what failed, why, and what to do next, instead of a bare "Failed", "Something went wrong" or the browser's "Failed to fetch".

The dashboard

One shared helper, resources/js/lib/errors.ts, used in about 35 screens:

  • The server's reason wins. Validation errors, error, the API's {error: {message, next_step}} and message are read in that order. Laravel's stock texts ("Server Error", "CSRF token mismatch.") and internals ("No query results for model [App\Models\…]") are replaced by plain ones per status: signed out, page open too long, no permission, too many tries, panel restarting.
  • Network failures are explained. "Failed to fetch" (and Firefox's and Safari's versions) becomes "Couldn't reach the panel. Check your connection and try again." When the page isn't on HTTPS, it says that, since a plain-HTTP page whose requests get redirected to HTTPS is a common cause on self-hosted panels. Offline says offline.
  • Code bugs don't leak. A TypeError or SyntaxError from the page shows a short fallback, not JavaScript internals. Cancelled requests don't show their URL.
  • Inertia page requests that fail on the network now show one toast (it replaces itself, so a page that reloads every few seconds while offline shows one, not many); before, nothing happened.
  • Failed jobs show their next step with the message, and when the panel doesn't recognise the failure, the line from the machine's output that says why: "apt-get exited 100. The machine said: E: Unable to locate package nginx-full". Not in the console, where the output is already on screen.

Screens covered include connecting a machine (its Advanced tab no longer spins forever when its options can't load), the welcome page, the setup wizard, deploys, the service page, firewall, tunnel, disk usage, files, database, console, updates and rollouts, job log, clone, app variables, alerts, logs, API and MCP keys, two-factor setup, Ask AI and the status page. Background polls stay quiet on purpose.

The server

  • Every job kind gets a cause and a fix, not just deploys: disk full, out of memory, package manager locked, package not found, port taken, no internet, timed out (DeployFailure::general()). Job answers in the API and MCP carry it as explanation.
  • Workflow steps say why they failed. The step's own message is shown; database and HTTP client errors stay hidden and are logged, so no table names or webhook URLs leak. A deleted machine, app or project says so instead of naming a model class.
  • Ask AI gives a reason when a job fails without a message, including the machine's line. Alerts don't get that line, since build output can carry secrets into Slack or email.
  • Console output stays private. Members who can't use the console already didn't get a command's log; they also no longer get the end of its output through error.output_tail. A console command's own output isn't explained as a machine problem.

Translations

New strings in Spanish, German and Hindi; 14 strings nothing uses any more removed.

Tested

  • Pest (new cases in tests/Unit/DeployFailureTest.php and tests/Feature/MachineServiceTest.php fail without the change), tests/js/errors.test.mjs with node --test, Pint, PHPStan, vp check and vue-tsc.
  • In the browser on a dev panel, old code against new: the Connect machine dialog with the request cut ("Failed to fetch" before, the HTTPS message after), with an expired session (419), normally, and the Advanced tab with its options cut, then recovering on Try again.

Before merging

Fixes #86

Most of this was generated by Claude.

@wrrfsub
wrrfsub requested a review from a team as a code owner November 16, 2026 12:23

@liamdevss liamdevss left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is a big improvement and mostly ready. It merges cleanly with main (including #94), vue-tsc is clean and the targeted tests pass. Two things before it goes in:

  1. resources/js/app.ts:93-96: don't preventDefault() every Inertia networkError. In Inertia 3.8 that event fires for any failed visit, not just network failures. Preventing the default skips onPrefetchError, so a failed prefetch stays "in flight" forever: the prefetch links in UserMenuContent.vue and AccountMenu.vue stop working until a full reload (and just hovering them on a flaky connection pops the toast). It also stops non-network errors, like a chunk that fails to load after a deploy, from reaching Sentry. Please drop the preventDefault() and only toast when isNetworkError(event.detail.error) is true.
  2. WorkflowEngine::readable(): any RuntimeException message becomes the step's message, and that goes into the workflow.failed alert (Slack, email, webhook). phpredis's RedisException is a RuntimeException, so "read error on connection to 10.x.x.x:6379" could reach a customer's Slack, and the same for other framework UnexpectedValueException/OutOfBoundsException types. Please check for exactly RuntimeException::class or use a dedicated user-facing exception class.

Optional, since the gap was there before: app/Mcp/Tools/Service/ServiceView.php:128-136 still returns error.output_tail for private console jobs through Present::job. An Arr::except($out['error'], ['output_tail']) there would make the "console output stays private" point true for MCP and Ask AI too.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Say why something failed and what to do next, not just "Failed"

2 participants