Troubleshooting

Each section names a symptom, its usual causes and what to do. The linked pages have the details. If none of this helps, write to support@mitjamartini.com.

Adding a project fails

Validate token answers with one of these:

• “Token was rejected.” Hetzner does not accept the token. Copy it again from the Hetzner Console (Security → API tokens), in full, from the project you mean to add.
• “Could not reach the API.” The iPhone has no connection, or a custom API endpoint under Advanced is wrong. Choose Standard unless you know you need another one.
• “Token works, but it can WRITE.” The app still only reads with it, but create a read-only token and use that instead.

See Connect a Hetzner project.

A project on this device: token rejected

“Token for … was rejected — it may have been revoked.” means Hetzner refused the project’s token, usually because someone revoked or rotated it in the Hetzner Console. The app shows the project’s last loaded state. Create a new read-only token, tap Fix in Settings, swipe the project away, and add it again with Add Hetzner project.

Costs differ from the invoice

The Costs tab is an estimate from Hetzner’s current list prices, net.

• VAT and discounts appear only on your invoice.
• An older rate. A server created before a price change keeps its old rate, and the API does not say so. Two labels on the resource correct it (Costs per customer with labels).
• approx. marks a price the app could not determine exactly, such as a load balancer whose type the inventory does not report.

See Costs.

The widget is out of date

Widgets make no network requests. They show what the app saved when it last refreshed, so open the app to update them. On Pro and Team, a warning or critical alert’s push notification also updates the widget. Siri answers from the same data, says how old it is when it is more than five minutes old, and answers “No health data yet” until the app has loaded your projects once. See Widgets, shortcuts and Siri.

A server stays on Waiting for agent

Waiting for agent in the app (Waiting in the portal) means the Vaicoa agent has never reported.

• The install did not finish. Run cloudviewer-agent status on the server. If it says “not enrolled”, run cloudviewer-agent enroll --token <agent_token> as root.
• The server cannot reach Vaicoa. The agent needs outbound HTTPS to api.vaicoa.com on port 443.
• The token is wrong. It is shown only once. Create a new one with Rotate token under Monitored Servers in the portal, then enroll again. A revoked token shows Agent revoked instead.

In the portal, Stale means the server last reported more than 5 minutes ago, Offline more than an hour ago. See Install the agent and the Agent reference.

A row is grey

Grey means no data, not down. Vaicoa could not observe that day or that moment: the row is younger than the window, our own monitoring could not reach it, or a free account’s checks were paused (see No data). Grey time is left out of the uptime percentage. See The dashboard.

No push notifications arrive

• Alerts need Pro or Team. Free mode and a free account get none.
• Notifications are off for the app in the iPhone’s settings.
• Test it. Settings → Notifications → Send test notification sends a test to every device signed in to your account. If it arrives, delivery works.
• You signed out. Signing out stops all push notifications to the device.
• Another team. A phone gets alerts for every team you signed in to on it. Leaving a team stops its alerts.
• The alert is muted. Check Active alerts for a muted badge.

See When something needs attention.

A connected project shows “Token revoked or invalid”

Hetzner refused the project’s token on three syncs in a row. The project stops syncing. An admin creates a new read-only token and uses Replace API token on the project in Hetzner Projects; syncing resumes within a minute, with history kept. See Connect a Hetzner project.

A check shows Mixed

The two networks disagree: one reaches the endpoint, the other does not. Usually a firewall, WAF, rate limiter or geo-block lets only some sources through, or one route to your host is broken. Mixed never alerts. Allow requests with the User-Agent CloudViewer-Check/1.0; the checks’ source addresses are not published. See Uptime checks reference.

A check shows No data

Neither network has reported. No data is grey, sends no alert and does not count as downtime.

• The check is new. The first results arrive within a few minutes.
• A free account’s checks paused after 60 days without anyone on the team using the app or the portal. Your visit starts them again within a minute or two.
• Our side had a problem.

An alert target switched itself off

After 20 failed attempts in a row, one a minute, a target switches itself off. The portal’s Alerts page shows when, with the last error. Common causes: the receiver is down or slower than 5 seconds, answers with a status other than 2xx, or the URL redirects (redirects are not followed; enter the final URL). Fix the receiver, use Switch it back on, then Send a test event. See Send alerts where you work.

The digest did not arrive

• Nothing started or resolved. There is no email for an empty period, even while an alert is still firing.
• The recipient must be a team member with a verified email address. If the address is no longer verified, nothing is sent; choose a recipient again under Alerts.
• It is not due yet. The daily digest goes out at 07:00 UTC, the weekly one on Monday, the four-hourly one four hours after the previous.
• Muted alerts are never included, and Which alerts may be set to critical only.

The digest is written in the recipient’s language, set in their portal profile. See Send alerts where you work.

A job shows Stale although it ran

Stale counts from the last successful run. A run that exited with a non-zero code does not reset it.

• The report did not arrive. cloudviewer-report says why on stderr: “job ran, not reported” when it found no token, often because a non-root cron user cannot read /etc/cloudviewer-agent/agent.env, or “not accepted” with the HTTP status.
• --max-age is too tight. A daily job with --max-age 24h goes stale when one run starts late. Use 26h.

A job that has never succeeded never goes stale; it only gets Job failed. See Get told when a job fails.

Log lines are missing

• Log context needs the agent, on Pro or Team.
• Only warnings and worse are sent: journald priority 0–4. Info and debug lines are not. Write your own with logger -p user.warning.
• Lines written only to a file are not collected; the agent reads journald.
• The busiest minute keeps its first 120 lines. The screen then says that some lines were rate-limited. Lines longer than 2,048 bytes are cut.
• Lines are kept 72 hours, or 2,000 lines per server.
• SSH and sudo lines need Team, an admin’s opt-in under Log Collection, and a system that writes /var/log/auth.log or /var/log/secure.

See Log context.

Costs look wrong for a dedicated server

Dedicated servers are not in the Hetzner Cloud API, so their price cannot be looked up. They count as €0 until an admin enters the price with Set price under Monitored Servers in the portal. The same applies to check targets. See Costs.

A server went down and no alert came

• The team is not on Pro or Team. Free accounts get no alerts.
• The alert is muted, or it went to a channel you do not watch. Check the alert’s history on the server’s detail screen.
• The server never reported, or only sends job reports. stopped reporting needs agent metrics to have arrived at least once.
• Less than 5 minutes have passed. The agent sends every 30 seconds; the alert fires after 5 minutes of silence.
• A cloud server you registered with its own agent token is not linked to its Hetzner resource. It still gets stopped reporting, but its Hetzner alerts are separate. Use a fleet token for cloud servers.

See Alert rules.