Background jobs

Recover from a failed job

A failed job stays failed until someone acts on it. This page shows where to find the reason and what to do next for each kind of job.

In the app: Settings › Organization Settings › Background Jobs tab

Find the reason

  1. Open the Background Jobs tab (or Schema Imports for an import).
  2. Find the row with the red Failed badge.
  3. Read the Message column. It holds the error.
  4. If the job has its own screen, open it for the full detail.

Two causes to rule out first

  • The AI usage allowance ran out. If the message says the monthly AI usage allowance is exhausted (or “AI token allowance exhausted after N of M”), AI work can’t continue until the allowance is topped up or the next period starts. A description job that runs out part-way keeps what it already wrote. See AI usage allowance.
  • The organization is read-only. Jobs that change content can’t start while the organization is read-only. See Account states and read-only mode.

By kind of job

Schema import

  • Open the import from Schema Imports. The detail page lists each failed object with its error.
  • Click Fix on a failed object to correct its DDL and retry it. See Fix failed import items.
  • Click Resume All Failed to retry every failed object at once, or Download Failed DDL to fix them outside Kenseme.

Description generation

  • The message usually names the object the AI couldn’t handle.
  • Try again on a smaller selection, or on that object alone.
  • Very long SQL bodies are the usual cause; describe that object by hand if it keeps failing.

SQL object analysis

  • Analysis fails most often when a body doesn’t parse cleanly.
  • Fix the syntax on the object’s script tab and run the analysis again.
  • If the SQL is valid but written for another database, check the schema’s dialect on its Settings tab.

Pipeline AI rename, procedure generation, or finalize

  • Run Validate on the Pipeline. Most generation failures come from a mapping problem that validation points out.
  • Fix what it reports, then generate again. See Validate a Pipeline.

Star schema design or build

  • Open the schema’s Star Schema tab to see the run’s result, then run it again. A build where only some items failed finishes with errors rather than failing outright.
  • See Star schema overview.

Ontology Generator

  • The run page shows where the agent stopped. Click Edit configuration to adjust sources or the prompt, or Re-run to try again. Nothing reached your ontology, because changes are only saved when you accept them in the review.
  • See Generate an ontology with AI.

Ontology import, standard import, or version deploy

  • The message usually points at the file or item that couldn’t be read or written. Check the file is valid Turtle, RDF/XML, or another supported format and import it again. See Create or import an ontology.

Retries

A few jobs retry once or twice on their own when a problem looks temporary, such as a brief network error. Jobs that change a lot at once, including schema imports, Pipeline generation, and ontology generation, don’t retry automatically, because a blind retry could hide the real problem. Fix the cause, then start the job again.

A failed job never undoes the work it finished before it failed.

When to escalate

Contact your Kenseme support contact when:

  • the message is generic and gives you nothing to act on;
  • the same job keeps failing after you’ve fixed the obvious cause;
  • several unrelated jobs fail at the same time.

Send the Job ID, the time it failed, and a copy of the Message. That’s enough for support to find it.