VegaGraph troubleshooting
Diagnose validation, identity, context, traversal, search and authorization problems.
| Symptom | Inspect first | Likely cause |
|---|---|---|
| Entity create conflicts | FQN and aliases in the workspace | Existing canonical identity or duplicate source mapping |
| Aspect write rejected | Aspect type JSON Schema | Missing required field, wrong type, unsupported property |
| Required aspect error | Entity-type aspect bindings | Required binding absent or invalid default data |
| Edge rejected | Relationship type and endpoints | Type/category mismatch, field endpoint disallowed, cardinality or cycle |
| Context edge rejected | Endpoint and edge contexts | Mixed environment-specific endpoints or invalid inheritance |
| Traversal seems incomplete | Direction, type filter, context and depth | Wrong edge direction, permission filtering, bounded result |
| Two apparent copies of an asset | FQN, external ID, source and aliases | Connector created instead of reconciling identity |
| Search misses a known entity | Search document and searchable fields | Projection absent/stale, field intentionally excluded, authorization |
| Delete returns conflict | Dependencies and built-in status | Active edges/bindings, required parent, protected system type |
| PATCH did not clear a field | Patch contract | Omitted value preserves data; use allowed clear_fields entry |
Identity reconciliation
Before creating an entity, resolve by stable source identity, FQN and known aliases. When a source object is renamed, update the existing entity and add its former name as an alias if identity is certain. Never merge two entities merely because their display names match.
Schema validation
Read the current aspect type and validate locally against its JSON Schema. The graph validates again at write time. If a connector cannot map a new source value, preserve the source observation outside the governed aspect until the type contract is intentionally evolved.
Relationship failures
Check the relationship contract in this order:
- source and target direction;
- allowed entity types/categories;
- field endpoint allowance and parent ownership;
- selected context;
- existing edges that consume cardinality;
- paths that would create a prohibited cycle.
Use type-impact preview before weakening a contract to accept one edge.
Context surprises
Current aspect reads can include canonical and inherited facts. Inspect the returned origin and context ID. If production displays a staging fact, correct the source context/FQN rather than hiding origin in the client.
Search diagnosis
Fetch /entities/{id}/search-document. If absent or stale, rebuild it from approved current aspects. If correct, verify query filters, context and search permission. Search is eventually refreshed derived data; the entity/aspect API remains the authority.
Support bundle
Include organization/workspace, entity/type/context IDs, FQNs, relationship type and direction, structured error code, request ID, relevant resource versions and a redacted request body. Do not include secret values, unrestricted aspect payloads or sensitive search content.