> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/control-center/govern/govern-graph/troubleshoot-govern-graphs.md).

# Troubleshoot govern graphs

Fix failed uploads, missing relationships and fields, and agents that can't use a govern graph. Contact support if your problem isn't listed.

Find the cause of a failed upload, unexpected graph content, or an agent that can't use a govern graph. If your problem isn't listed, see [Get help](#get-help).

## Upload and build

### The upload fails with a package error

**Issue**. The **Failed** badge on the graph's row shows a reason about the package, such as a missing `nodes` object.

**Cause**. The package doesn't match the structure Qore expects. See [Error messages](#error-messages) for each reason. The table gives the exact text.

**Solution**. Fix the package, and then upload it again.

1. Find the reason in [Error messages](#error-messages).
2. Correct the package file.
3. Upload it again, or select **Upload new version** if the graph already exists.

### The build fails without a reason

**Issue**. The row reads "The build failed without recording a reason."

**Cause**. The build stopped before a reason was recorded.

**Solution**. Try the build again.

1. Select **Retry** on the graph's row, or upload the package again.
2. If it fails the same way, contact your Uptiq administrator with the graph name and the time of the failure.

### A file can't be selected

**Issue**. The file chooser doesn't accept the package.

**Cause**. The file isn't a `.json` file, or it's larger than 80 MB.

**Solution**. Use a `.json` file of 80 MB or less.

1. Export the package as one `.json` file.
2. Check that the file is 80 MB or less.

### Upload Govern Graph isn't available, or the upload is refused

**Issue**. **Upload Govern Graph** isn't available, or an upload is refused.

**Cause**. Uploading needs the **Ingest source & extract knowledge graph candidates** capability. Approver and Auditor can view graphs only.

**Solution**. Ask an administrator for the Governance Manager, Account Admin or Org Admin role. See [Roles](https://docs.uptiq.ai/ai-workbench-qore/control-center/admin/roles.md).

## Graph content

### The graph has fewer relationships than the package

**Issue**. The graph's relationship count is lower than the number of edges in the package.

**Cause**. Qore skips edges whose `from` or `to` isn't a node in the package. Edges from regulatory obligation IDs are always skipped.

**Solution**. For obligation `seeds` edges, nothing to fix. For other edges, check that both ends are nodes in the same package.

1. Open the package and find the skipped edge.
2. Check that its `from` and `to` values match node IDs in the package.
3. Upload the corrected package as a new version.

See [Graph package](https://docs.uptiq.ai/ai-workbench-qore/control-center/govern/govern-graph.md#graph-package).

### A field from the package is missing on a node

**Issue**. A field in the package doesn't appear on the node.

**Cause**. Qore ignores some fields, such as `seeded_by`. It also doesn't store a `null` or empty list value.

**Solution**. Give the field a value in the package if it matters, and upload a new version. Ignored fields aren't stored under any value.

### Field or relationship names look different

**Issue**. A field name or relationship type doesn't match the package.

**Cause**. Qore stores field names in camelCase and relationship types in upper snake case.

**Solution**. Nothing to fix. For example, `effective_from` is stored as `effectiveFrom`, and `governed_by` is stored as `GOVERNED_BY`.

### Customer and Account show zero

**Issue**. The **Customer** and **Account** object types have no nodes.

**Cause**. Member data is never collected into the graph, by design. It's resolved from your core systems when an agent needs it.

**Solution**. Nothing to fix.

### Attestations disappeared

**Issue**. Nodes you attested on the **Sign-off Queue (Preview)** are unconfirmed again.

**Cause**. The **Sign-off Queue** is a preview, and attestations made there aren't saved.

**Solution**. Nothing to fix.

## Agents

### The agent says it has no governance graph to query

**Issue**. The agent reports it has no governance graph to query.

**Cause**. No govern graph is attached to the agent.

**Solution**. Attach the graph to the agent as knowledge.

1. In Agent Builder, select **+ Add Knowledge**.
2. Select the graph in **Use Existing Knowledge**.
3. Select **Add**.

See [Attaching Knowledge to an Agent](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent.md#attaching-a-govern-graph).

### An agent's answer looks incomplete

**Issue**. The agent's answer leaves out matches you expect.

**Cause**. Knowledge Graph Search returns at most 25 rows per query, and tells the agent when more matches exist.

**Solution**. Ask a narrower question, such as one product or one policy domain.

## Error messages

| Error message                                                                | Cause                                                                              | Solution                                                                                             |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Graph package is missing a `nodes` object                                    | The package has no top-level `nodes` object.                                       | Put the nodes in a top-level `nodes` object, keyed by category: `{ "nodes": { "Product": [ … ] } }`. |
| Graph package is missing an `edges` array                                    | The package has no top-level `edges` array.                                        | Add a top-level `edges` array, even an empty one.                                                    |
| A node in the graph package is missing its id                                | A node has no `id`.                                                                | Give every node an `id`.                                                                             |
| The graph package holds more than one node with the same id                  | Two nodes share an `id`.                                                           | Give every node its own `id`.                                                                        |
| A nested field in the graph package uses a name the graph structure reserves | A nested field uses a reserved name, such as `governance` or `nested`.             | Rename the nested field.                                                                             |
| The build failed without recording a reason                                  | The build stopped before a reason was recorded.                                    | See [The build fails without a reason](#the-build-fails-without-a-reason).                           |
| Connection environment variables are not set                                 | The graph store isn't configured for your environment. The package isn't at fault. | Contact your Uptiq administrator.                                                                    |

## Get help

If your problem isn't listed, contact your Uptiq administrator. Include the graph name, the exact error text, the time it happened, and the package file if the upload failed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/ai-workbench-qore/control-center/govern/govern-graph/troubleshoot-govern-graphs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
