Docs · Troubleshooting

When a run fails

Runs that break, return nothing, or quietly return less than they should.

#The run failed

Open the Run log on the Result tab. It heads itself either Healthy or with a count of things to look at, and its Run tab carries the error.

The Request tab on a data source is the one worth knowing about: it shows what Mosaic sent, captured before the call went out, with credentials redacted. A connection that failed outright still tells you what it tried — which is usually enough to spot a wrong port, an unresolved token or a query that is not the one you thought you were running.

#A parameter stopped it

A run will fail: this parameter …

By default a number or date parameter with no value fails the run rather than quietly sending nothing.

Either give it a default, override it for this run, or — if empty really is a legitimate value — turn on Empty for that parameter, which sends NULL instead. See Parameters.

#A token did not resolve

A URL that still visibly reads {{host}}/api in the Request tab means nothing defined host. Mosaic leaves unresolved names alone rather than blanking them, precisely so this is visible.

Check, in resolution order: is it defined as a library variable, a parameter on this Check, or a variable in the active environment? And remember the active environment is per person — yours may not be the one your colleague was using when it last worked. See Environments and variables.

#The Check ran clean but compared nothing

Total rows 0, differences 0, every Rule passed. This is the dangerous one, because it looks like success.

A query that returns nothing produces no disagreements. If the source silently broke — a table renamed, a date parameter pointing at a day with no trading, a filter that excludes everything — the Check will keep reporting all-clear indefinitely.

Fix it structurally: add a Rule of rows compared, at least 1. Every scheduled Check should have one. See Rules.

#Some hosts did not answer

When a source fans out across many machines, a host that is unreachable does not fail the run — it is reported.

Open the Hosts tab in the run log. Each host says whether it answered, was unreachable, or failed, and with how many rows. A probe says the same: "Connected in 340 ms — 2 of 20 hosts unreachable".

Rows from an unreachable host are not missing data in the reconciliation sense, and Mosaic keeps them out of the verdict: those rows read Unable to connect rather than Missing. Treat a recurring unreachable host as an infrastructure problem, not a data one.

#The result was cut short

Rows marked Not read — row limit mean the comparison stopped before reaching them. Narrow the run — a parameter for one day or one region — or raise the limit on the source's Settings if the box can take it.

#An old run has no rows

Opening a run from history shows its counts but not its rows, with a note that they are no longer kept.

That is expected. History keeps counts for many runs; snapshots keep the actual rows for a much shorter window, measured in days. The run is not corrupt — the rows have aged out. Press Run now to ask the systems again.

Note that the expiry message says seven days. Seven is the Pro figure; your tier may be one, thirty or ninety. See Runs and history.

#Mosaic cannot reach its server

The page loaded but the API did not answer.

Not a password problem. The browser got the app but not the API. Check the server is running, and that anything in front of it — a proxy, a load balancer, an ingress — passes /api through to it.

#Sign-in says the details do not match

Every sign-in failure gives the same message and takes the same time, whether the account does not exist, the password is wrong, or the account is disabled. That is deliberate: it stops the screen being used to discover which addresses have accounts.

There is no self-service password reset. An admin resets it from the People screen. If there is no other admin on a self-hosted install, the account has to be deleted and the installation claimed again. See First sign-in.

#Something was refused for licensing

A refusal names the limit, what you have, and what would raise it — and always ends with the same reassurance:

Data sources, drivers and the rows they hold are never counted, runs you start yourself are never refused, and nothing you already have is affected.

Ceilings only ever block creating something new. Reading, running and exporting are never refused for a limit.