hasura/graphql-engine · error · Error

Couldn't find relationship ${field.relationship} for field $

Error message

Couldn't find relationship ${field.relationship} for field ${fieldName} on target ${JSON.stringify(target)}

What it means

While building the JSON_OBJECT projection for a query, the agent looks up the relationship named by `field.relationship` via find_relationships against the tracked relationships for the target. If the target has no relationship with that name, the field cannot be expanded and a plain Error is thrown embedding the relationship name, field name, and target JSON.

Source

Thrown at dc-agents/sqlite/src/query.ts:136

  return escapeTableName(getTableNameSansSchema(tableName));
}

export function json_object(
  all_relationships: Relationships[],
  fields: Fields,
  target: Target,
  tableAlias: string,
): string {
  const result = Object.entries(fields)
    .map(([fieldName, field]) => {
      switch (field.type) {
        case 'column':
          return `${escapeString(fieldName)}, ${escapeIdentifier(field.column)}`;
        case 'relationship':
          const relationships = find_relationships(all_relationships, target);
          const rel = relationships.relationships[field.relationship];
          if (rel === undefined) {
            throw new Error(
              `Couldn't find relationship ${field.relationship} for field ${fieldName} on target ${JSON.stringify(target)}`,
            );
          }
          return `'${fieldName}', ${relationship(all_relationships, rel, field, tableAlias)}`;
        case 'object':
          throw new Error('Unsupported field type "object"');
        case 'array':
          throw new Error('Unsupported field type "array"');
        default:
          return unreachable(field['type']);
      }
    })
    .join(', ');

  return tag('json_object', `JSON_OBJECT(${result})`);
}

export function where_clause(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Fetch the agent's schema/relationships endpoint and confirm the relationship exists for that target
2. Fix the field definition to reference an existing relationship name, or drop the field
3. If the relationship should exist, verify the underlying FOREIGN KEY constraint is present in SQLite (PRAGMA foreign_key_list) so the agent introspects it
4. Clear and re-sync client metadata caches

Example fix

// before
{ fields: { artist: { type: 'relationship', relationship: 'artistRef', args: {...} } } }
// after (use the relationship name the agent reports)
{ fields: { artist: { type: 'relationship', relationship: 'artist', args: {...} } } }

const rels = await fetchSchemaRelationships(agentUrl, target); if (!(fieldName in rels)) throw new Error(`Unknown relationship ${fieldName}`);

const hasRelationship = (rels: Record<string, unknown>, name: string) => Object.prototype.hasOwnProperty.call(rels, name);

try { await agent.query(q); } catch (e) { if (/Couldn't find relationship/.test(String(e))) await refreshLocalSchemaCache(); throw e; }

When it happens

Trigger: Requesting a field whose definition references `relationship: 'X'` when the agent's relationship set for that target has no entry 'X' — e.g. stale field metadata, a typo'd relationship name, or querying a table whose FK-derived relationships differ from what the client assumes.

Common situations: Client-side schema/metadata cache is stale after the database schema changed (FK dropped or renamed); hand-written queries referencing relationships that only exist in another environment; drift between the agent's introspected schema and the client's model.

Related errors

• ${tableName.join('.')} is not a valid table
• `escapeTargetName` only implemented for tables and interpola
• Unsupported field type "object"
• Unsupported field type "array"
• Unsupported path on ComparisonColumn: ${[...path, selector].

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/3420d3816e8ee3c4. Report an issue: GitHub.