Query Troubleshooting

Start here#

Almost every query question is one of four things, and the response tells you which.

Check the compiled model first#

Whatever the symptom, start by asking Atlas whether the model it is querying still matches your branch:

GET /api/v1/branches/{branch}/domains/{domain}/world

{
  "entityCount": 634,
  "edgeCount": 73,
  "archetypeCount": 42,
  "compiledAt": "2026-08-03T09:14:22.881Z",
  "isStale": false,
  "compiledAtSha": "7f3d0884",
  "currentSha": "7f3d0884"
}

This read does not trigger a recompile, which makes it a better first move than recompiling straight away: a recompile can clear a symptom without telling you what it was, and it takes time on a large domain.

If compiledAtSha comes back blank, recompile once and the field is populated from then on.

Where you run the queries in this article#

POST /api/v1/branches/{branch}/domains/{domain}/queries

The body field is cypher:

{ "cypher": "MATCH (n:Pump) RETURN n.Label AS Pump LIMIT 10" }

A body with a different field name returns 400 and the message Cypher query string is required.

You can also paste any of these queries into Ask Gage, which prints result rows directly in the Atlas interface. See Querying with Cypher for the full picture of where queries run.

The query returns an error#

Atlas query errors are RFC-9457 problem documents (application/problem+json):

{
  "type": "https://atlas.timebase.io/errors/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Syntax error at line 1:24 - mismatched input ')' expecting {...}",
  "code": "Query.SyntaxError",
  "traceId": "00-9f2c...-01"
}

The code field is the one to branch on in your client and the one to log.

Query.NotCompiled (HTTP 400)#

Symptom: every query against a domain fails immediately, with:

Domain '<domain>' on branch '<branch>' has not been compiled.
Call PUT /api/v1/branches/<branch>/domains/<domain>/world first.

Cause: there is no compiled model for this branch and domain pair.

Fix: compile the domain. In the interface, open the domain and select Compile on its Overview view. Over the API:

PUT /api/v1/branches/{branch}/domains/{domain}/world

Atlas recompiles every domain it knows about automatically at startup, so you do not need to compile again after a restart. If one domain stays uncompiled, see One domain stays uncompiled after a restart.

If the compile itself returns 422, see The compile did not complete.

Query.SyntaxError (HTTP 400)#

Symptom: the detail starts with Syntax error at line:

Syntax error at line 1:24 - <parser message>

The two numbers are the line and the character position, counted from zero. Go to that spot first; the position is usually more useful than the parser message after the dash.

Both 'value' and "value" are valid string literals.

Query.Unsupported (HTTP 400)#

Symptom: the detail names a clause or function outside the supported set. These are the exact messages Atlas emits, so you can match what you see to a row:

avg() and round() are available, as are the other functions listed in Querying with Cypher.

Query.SemanticError (HTTP 400)#

The query parsed but does not fit the model.

valueAt() reads both bound and calculated compound properties.

Finding nodes without a relationship#

To list the nodes that have no outgoing relationship of a given type, return the full set including the empty rows and select the empty ones in whatever consumes the result:

MATCH (p:Pump)
OPTIONAL MATCH (p)-[:feeds]->(t)
RETURN p.Label AS Pump, t.Label AS Feeds

Rows where Feeds is empty are the pumps with no outgoing feeds relationship. Filtering on the relationship variable inside the query - WHERE r IS NULL - is not supported and returns HTTP 500.

An HTTP call returns an HTML page instead of JSON#

Two causes produce this symptom, and neither is a query problem.

No access token. Every /api/v1 route requires a Timebase Pulse bearer token, and authentication is on by default. A call with no token is redirected to the Pulse sign-in page, so your client receives an HTML login form where it expected JSON.

A URL Atlas does not recognise. Atlas serves its single-page application for any URL outside the API surface, so a mistyped route returns HTTP 200 with an HTML body rather than a 404.

If the response body starts with <!doctype html>, check your token first and then your URL. These are the current routes:

The query returns no rows#

You received a well-formed result with an empty data array, or fewer rows than you expect. Work down these causes in order.

Your changes are still in a draft session#

Symptom: you added a type or an instance, the save succeeded, the compile succeeded, and your query returns what it returned before.

Atlas keeps in-progress work in a private draft session until you publish it:

• A save that has outstanding validation violations is held in your draft session rather than written to the branch. The response carries an Atlas-Validation-Violations header with the count. A clean save has no such header.
• A compile run from inside a draft session builds your own copy and returns that result to you, leaving the shared model that everyone else queries in place. This keeps unpublished work out of other people's results.

Check whether you have one:

GET /api/v1/branches/{branch}/draft

Publish it:

GET  /api/v1/branches/{branch}/domains/{domain}/validation   # see what is outstanding
POST /api/v1/branches/{branch}/draft/publish                 # move the work onto the branch
PUT  /api/v1/branches/{branch}/domains/{domain}/world        # compile again

Every rule ID in the violation list is documented in Validation Rules Reference.

The compiled model is behind the branch#

Symptom: a recent change is not visible, and your save landed on the branch.

Check: GET .../world. If isStale is true, the branch has advanced past the commit the model was built from, in a way that touches this domain's files or a library it imports.

Fix: PUT .../world.

Compiling is idempotent and safe to repeat. If a compile does not complete, the model already in place keeps answering queries unchanged.

The compile did not complete#

Symptom: your compile returned HTTP 422 with a violations array, and queries return the previous data or Query.NotCompiled.

Cause: Atlas validates the whole domain before it builds, so one Error-severity violation stops the build. Nothing is partially compiled, and the model appears once the last Error is cleared.

Fix: read the violations, fix them, then compile:

GET /api/v1/branches/{branch}/domains/{domain}/validation

This returns the same violation records as the 422 body, plus errorCount, warningCount and blocking, and it changes nothing - use it as your fix-and-recheck loop. Every rule ID, its message and its fix is in Validation Rules Reference.

You are querying a different branch#

Symptom: the instances exist, and the query returns nothing.

The branch is part of the query URL, so querying main returns nothing when your instance maps are on a feature branch.

GET /api/v1/branches          # what branches exist
GET /api/v1/worlds            # which (branch, domain) pairs are compiled

GET /api/v1/worlds answers "which branch has a model?" in a single call.

The type name or property name does not match#

Symptom: a query returns nothing, or a column comes back empty, and the type or property does exist.

Names are matched exactly, including case: Pump is not pump, and Speed is not speed. A type or relationship name in a MATCH pattern that matches nothing is an error, Unknown label or Unknown relationship type under Query.SemanticError, so an empty result means the names resolved and the rows are genuinely absent. A property name that matches nothing returns an empty column rather than an error, and a WHERE n:Type predicate with an unknown type filters every row out.

Two names worth knowing:

• The universal display name is .Label, with a capital L.
• A property fed by a connector is a three-part value. Reading n.Speed gives you the reading, its timestamp and its quality together. The number is n.Speed.Value.

List what is actually there:

MATCH (n)
RETURN DISTINCT labels(n) AS Type, count(n) AS Count
ORDER BY Count DESC

MATCH (n:Pump)
RETURN keys(n) AS Properties
LIMIT 1

Both return full internal addresses, such as urn:atlas:ontology:lonestar-plant:Plant. In your own MATCH, use the last segment after the final colon, so that becomes MATCH (n:Plant).

One domain stays uncompiled after a restart#

Symptom: after an Atlas restart, most domains work but one keeps returning Query.NotCompiled.

Atlas recompiles every domain it has a record of at startup, in the background, while continuing to serve traffic. Domains become queryable one at a time as each recompile lands, so a brief Query.NotCompiled immediately after a restart clears itself.

Domains bound to a connector are compiled when their connector registers rather than at startup, so a domain waits until its connector is online.

Check the connectors:

GET /api/v1/connectors

Each entry gives you connectorId (the stable identity, such as conn.historian), displayName, datasourceCount and registeredAt. The transportId field is the current live connection id and changes on every reconnect, so use connectorId for identity.

The query returns rows you did not expect#

These are the rules that decide which rows come back. Each one parses cleanly and returns HTTP 200, so if your query runs but the numbers are not what you expect, start here.

A type on the far end of an arrow filters that node#

A type written on any node of a pattern filters that node, not only the first one:

MATCH (line:Line)-[:contains]->(p:Pump)     -- returns only the pumps
RETURN line.Label AS Line, p.Label AS Pump

The match understands type inheritance, so it also matches anything defined as a kind of Pump. On a variable-length pattern such as (root)-[:contains*1..8]->(p:Pump), the type applies to the final node only; the nodes in between are not constrained. shortestPath applies the types at both ends. Earlier 2.0 builds applied only the type on the start node; if a type on the far end of an arrow is ignored, you are on one of them.

Ask Gage

Ask the graph-query agent: "List the pumps on each line, and explain how the Pump type narrows the result."

It returns the query with the type on the pump node and explains what the type matches.

An inline map is an equality on each key#

MATCH (p:Pump {Label: 'P-001'}) and MATCH (p:Pump) WHERE p.Label = 'P-001' are the same query. A map with several keys requires all of them, and it combines with any WHERE you also write. Two things to know:

• A bound property is a compound, so {Speed: 42} compares the whole three-part value and matches nothing. Name the part with a dotted key, {Speed.Value: 42}, or write WHERE p.Speed.Value = 42.
• Anything other than equality, such as > or STARTS WITH, goes in WHERE.

Earlier 2.0 builds dropped inline maps and returned the unfiltered rows; if a map has no effect, you are on one of them.

Use labels(n) without a subscript#

labels(n) returns a single-element list, which is readable as-is:

MATCH (n)
RETURN DISTINCT labels(n) AS Type, count(n) AS Count
ORDER BY Count DESC

List indexing and slicing, such as labels(n)[0], are not part of Atlas Cypher. Read the last segment of the address you see.

Matching a type also returns everything beneath it#

MATCH (n:Equipment) matches Equipment and every type defined as a kind of Equipment - pumps, tanks, motors. This is usually what you want, and it is the most likely reason a count is higher than you expected.

To work with the parent type alone, return labels(n) alongside your rows and select the exact type in whatever reads the result.

More than one label on a node requires all of them#

MATCH (n:Machine:Active) returns only nodes that are both Machine and Active. It is the same query as:

MATCH (n:Machine) WHERE n:Active

Write the full address when a short name is ambiguous#

Atlas resolves a type name by trying the full address first, then matching on the last segment. If two scopes in your model declare the same local name, write the complete address in the pattern:

MATCH (n:`urn:atlas:ontology:{scope}:{Name}`)

The same applies to property names. On a pattern that carries a type, a short property name is resolved against that type's own hierarchy. On an untyped pattern such as MATCH (n), there is no type to scope against, so put a type on the pattern whenever you read properties.

Deduplicating a collected list#

count(DISTINCT ...) removes duplicates. For a distinct list from collect(), deduplicate outside the query or structure the match so duplicates do not enter the collection.

Sort a UNION result outside the query#

ORDER BY, SKIP and LIMIT after a UNION apply to each branch, and the branches are then stacked. Sort and page the combined result in whatever consumes it.

Write the depth on a variable-length traversal#

[:contains*] walks to a depth of 10 by default, and 50 is the maximum. Write the depth you need explicitly:

MATCH (plant:Plant)-[:contains*1..15]->(child)
RETURN plant.Label, count(child) AS Descendants

Anchor a regular expression#

=~ matches anywhere in the string, so WHERE n.Label =~ 'P-[0-9]{3}' also matches SUMP-9999 and P-12345. Anchor it with ^ and $, or use STARTS WITH, ENDS WITH or CONTAINS.

Use a decimal when calculating a percentage#

Whole number divided by whole number gives a whole number, so Volume / Capacity * 100 turns 450 out of 1000 into 0. Multiply before you divide, and use a decimal:

RETURN n.Volume.Value * 100.0 / n.Capacity AS PercentFull

Dividing by zero produces an empty value, and that row is not returned.

The durable identifier is entityId#

MATCH (n:Pump)
RETURN n.Label AS Pump, n.entityId AS Id, n.typeId AS Type

entityId is the stable handle and typeId is the type's full address. id(n) is a positional number that changes on every compile, so use entityId in anything you store.

Reading a live value#

An unsampled value reads as null#

A property that has not yet received a sample holds no value, so each of its fields reads as null:

A written zero is a value and reads as 0 or 0.0, so null and zero are different things. Return the fields alongside each other:

MATCH (n:Pump)
RETURN n.Label AS Pump,
       n.FlowRate.Value AS Flow,
       n.FlowRate.Timestamp AS ReadAt,
       n.FlowRate.Quality AS Quality
ORDER BY ReadAt

Rows with a null ReadAt sort to the end of the list, and they are the ones waiting for their first reading. To list only those, filter on the property:

MATCH (n:Pump)
WHERE n.FlowRate IS NULL
RETURN n.Label AS Pump

A compound property that has never received a sample is null as a whole. Once any field holds a value it is a three-part value again, so to find a null value field in particular, test the field: WHERE n.FlowRate.Value IS NULL. Aggregates such as avg, sum, count, min and max ignore null cells.

The three states:

Check the value without writing Cypher:

GET /api/v1/branches/{branch}/domains/{domain}/instances/{instanceId}/values

This returns a snapshot of one instance's property values at the moment you call it, which separates "is the value there?" from "is my query right?". It returns 400 if the domain is not compiled and 404 if the instance is not in the compiled model, so the status code distinguishes those two states.

Use UNWIND for historical values#

valueAt(n.Speed, ...) returns the property's current in-memory value. To read history, expand the property with UNWIND, which is the shape that reaches the data source:

MATCH (a:Agitator)
UNWIND a.Vibration AS v
WITH a, v
WHERE v.Timestamp >= datetime('2026-08-01T00:00:00Z')
RETURN a.Label AS Asset, v.Timestamp AS Time, v.Value AS Vibration
ORDER BY Time

valueAt() returns null in three cases: the timestamp could not be read (it accepts a whole number of ticks, a date-and-time value, or a parseable date string), the first argument does not resolve to an instance, or the property name did not resolve.

Historical values return no rows#

UNWIND over a connector-fed property fetches readings from the source, so it is the one query shape whose speed and results depend on a system outside Atlas.

Use datetime('2026-08-01T00:00:00Z') for a fixed point and relative('-24h') for a rolling window. Both are covered in Querying with Cypher.

Diagnostic queries#

What types exist, and how many of each:

MATCH (n)
RETURN DISTINCT labels(n) AS Type, count(n) AS Count
ORDER BY Count DESC

What relationships exist, and how many of each:

MATCH ()-[r]->()
RETURN DISTINCT type(r) AS Relationship, count(r) AS Count
ORDER BY Count DESC

What properties a type has:

MATCH (n:Pump)
RETURN keys(n) AS Properties
LIMIT 1

Total instance count, as a check against the compile result:

MATCH (n) RETURN count(n) AS Total

Which instances are waiting for their first sample:

MATCH (n:Pump)
RETURN n.Label AS Pump,
       n.FlowRate.Value AS Flow,
       n.FlowRate.Timestamp AS ReadAt
ORDER BY ReadAt

Rows with a null timestamp at the end of the list have not received data yet.

Ask Gage

Ask the graph-query agent: "Find every pump property across my domain with a year-1 timestamp, and group them by source. Which bindings or connectors have not sent their first reading?"

It separates properties waiting for a first sample from genuine zero readings, and points you at the source to check.

What is directly under something:

MATCH (p:Pump)<-[:contains]-(parent)
RETURN parent.Label AS Parent, p.Label AS Pump
ORDER BY Parent

Diagnostic API calls#

All of these need a Timebase Pulse bearer token.

Quick reference#

Related articles#

• Querying with Cypher - what the language supports, where you run a query, and the ready-made patterns. Read this first if you are still writing the query.
• Validation Rules Reference - every validation rule ID, its message, and how to clear it. Read this when a compile returns 422.