Issues

An issue is one root cause on one item type. When the same problem stops twenty records from publishing, you get one issue that says it affects twenty records, not twenty near-identical rows to read through. Open an item type in Databases and go to the Issues tab. The tab itself carries a count of the records still affected, so you can see there’s something to fix without opening it.

​

What the list shows

Each row is one issue:

• Status: Open while anything is still failing, Resolved once everything it held up has gone through.
• Issue: the category, a short title, and a sentence naming the field and value behind it.
• Affected: how many records are still affected. Ingestion and workflow issues count runs, schema issues count changes, and a resolved issue reads None open.
• First seen and Last seen: when Serval first hit this cause, and the most recent time it hit it again.

Above the list, a summary counts the whole page: 12 affected records across 3 issues. A trailing + means more issues are still to load.

​

Categories

​

Filters

• Category: narrow to one of the categories above.
• Source: only issues from one ingestion source.
• Rule: only issues from one validation rule.
• Time range: how far back to look, by the last time each issue was seen.
• Include resolved: add issues that nothing is failing on any more.

​

What an issue tells you

Select a row to open it. The drawer names the item type, when the issue was first and last seen, and how many records are open out of everything it has ever affected. Message says what went wrong in plain terms, with the field, the value from the source row, and the record involved resolved to their names. Alongside it are the one or two places worth going next: the ingestion sources for a relationship that matched nothing, the source rows for an empty key, the record that already holds a value, or the rules that rejected a record. Diagnostics is collapsed and holds the raw error text, for issues that have one. Affected records lists every record, run, or change under the issue, 50 at a time. Each entry links to the record where there is one, lists the source rows that fed it, names the rules it broke, and gives the times it was seen and resolved. Load more pages through the rest.

​

Fixing an issue

Nothing here is marked done by hand. An issue resolves when the thing that failed succeeds: the next sync publishes the record, the schema change is retried and applies, the held run is replayed. Fix the cause and the issue clears on its own. Common causes and what to change:

• Relationship target not found: the source value doesn’t match any record in the linked table. Check that the linked table is ingested and that the field is mapped.
• Key field is empty: the source row has no value for the key field. Fix it at the source, or map the key to a field the source always fills.
• A value already belongs to another record: two records want the same unique value. Give one of them a value of its own.
• Records rejected by validation rules: either the data is wrong or the rule is. The issue names the rule so you can decide which.
• Run failed: the sync itself stopped. See Reading sync history below.

​

Reading sync history

Open the ingestion’s Sync History to see each run’s status and result. A run that published only some of what it ingested says how many records publishing rejected, with a View issues link to the item type’s issues for anyone who can open them.

​

Failure causes

A failed run reports a specific cause rather than a generic error:

• The extraction workflow failed on page N: the ingestion workflow returned a failure. Open the run to see why.
• The extraction workflow didn’t finish page N in time: the workflow ran past its time limit. Usually pagination pulling too much per page.
• The extraction workflow returned a result Serval couldn’t read: the response didn’t match what an ingestion workflow returns, or the run switched between a full and an incremental result mid-sync.
• The extraction workflow isn’t published: publish it, then sync again.
• Couldn’t store the ingested data: Serval couldn’t write a page of records. Retry the sync.
• Ingested data couldn’t be published: the records were stored but publishing them failed. The reason is on the Issues tab.
• The sync stopped making progress: the run made no headway across several attempts and stopped retrying on its own. Use Resume on the run to try again from where it left off.
• A newer sync run replaced this one: a later sync started before this one finished. Nothing to do.

​

Run timeline

Expand a run to see its timeline: when it started, resumed, changed phase, or continued, and every failure along the way. Each event names the page it’s about and carries its own diagnostics. Three events explain a run that looks clean but did less than you expected:

• Rows skipped: a page couldn’t stage some of its rows, and the event counts each kind: rows with no id, duplicate ids within one page, and deletes naming rows Serval isn’t currently ingesting.
• Publishing skipped: the run ingested records but published none, because the source has no field mappings.
• Sync ended after stalling: the run stopped making progress and Serval ended it.

​

What’s next