What causes "Expected start of dependency link object but was {}" in openzipkin/zipkin?

Inspect documents in the zipkin:dependency indices (GET /_search) and confirm each hit _source is an object with parent/child/callCount.

openzipkin/zipkin · error · IllegalArgumentException

Expected start of dependency link object but was {}

Error message

Expected start of dependency link object but was {}

What it means

DEPENDENCY_LINK_PARSER decodes each element of the dependency-link array returned by Elasticsearch and requires a JSON object start; any other token throws IllegalArgumentException('Expected start of dependency link object but was <token>'). Dependency links are read when getDependencies() aggregates the dependency indices.

Source

Thrown at zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/internal/JsonSerializers.java:190

          timestamp = parser.getLongValue();
          break;
        case "value":
          value = parser.getValueAsString();
          break;
        default:
          // Skip
      }
    }

    if (timestamp == 0 || value == null) {
      throw new IllegalArgumentException("Incomplete annotation at " + parser.currentToken());
    }
    return Annotation.create(timestamp, value);
  }

  public static final ObjectParser<DependencyLink> DEPENDENCY_LINK_PARSER = parser -> {
    if (!parser.isExpectedStartObjectToken()) {
      throw new IllegalArgumentException("Expected start of dependency link object but was "
        + parser.currentToken());
    }

    DependencyLink.Builder result = DependencyLink.newBuilder();
    JsonToken value;
    while ((value = parser.nextValue()) != JsonToken.END_OBJECT) {
      if (value == null) {
        throw new IOException("End of input while parsing object.");
      }
      switch (parser.currentName()) {
        case "parent":
          result.parent(parser.getText());
          break;
        case "child":
          result.child(parser.getText());
          break;
        case "callCount":
          result.callCount(parser.getLongValue());

View on GitHub (pinned to 878ce2a1fa)

Solutions

Inspect documents in the zipkin:dependency indices (GET <index>/_search) and confirm each hit _source is an object with parent/child/callCount.
Fix or remove whatever wrote malformed dependency documents.
Reindex/delete bad documents so getDependencies stops failing.
Use Zipkin's own DependencyLink store/serializer when producing links programmatically.

Example fix

// before: dependency index doc _source = ["frontend","backend",3]
// -> IllegalArgumentException: Expected start of dependency link object but was START_ARRAY

// after: _source = {"parent":"frontend","child":"backend","callCount":3}

Defensive patterns

Strategy: type-guard

Validate before calling

var link = objectMapper.readTree(dependencyJson);
if (!link.isObject()) {
  throw new IOException("dependency link must be an object with parent/child/callCount");
}

Type guard

boolean dependencyLinkWellFormed(JsonNode n) {
  return n.isObject() && n.has("parent") && n.has("child") && n.has("callCount");
}

Try / catch

try { DependencyLink l = DEPENDENCY_LINK_PARSER.parse(p); }
catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Expected start of dependency link object")) {
    // malformed doc in dependency index: locate and reindex/delete it
  }
}

Prevention

Write dependency links only via Zipkin's DependencyLink serde (parent/child/callCount objects).
Periodically validate document shapes in zipkin:dependency indices if external jobs write to them.
Keep external writers out of Zipkin-managed indices.

When it happens

Trigger: A document in a zipkin:dependency-* index whose top-level shape is not an object (array/scalar), or a converter feeding the parser at the wrong depth, when BodyConverters.DEPENDENCY_LINKS parses search hits.

Common situations: Custom jobs writing dependency data directly into Zipkin's dependency indices with wrong framing; corrupted index contents; version-skewed reads; tests with wrong fixtures.

Related errors

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/a8fa3dec6ed5977e. Report an issue: GitHub.