> For the complete documentation index, see [llms.txt](https://docs.githud.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.githud.net/command-interface/error-codes-and-troubleshooting.md).

# Error Codes & Troubleshooting

## Error Codes & Troubleshooting

While Githud's zero-trust cryptographic architecture ensures unparalleled security, it can occasionally present complex error states when misconfigurations occur. This troubleshooting guide is designed to help you quickly identify and resolve the most common cryptographic and operational failures encountered by the CLI and autonomous agents.

### Common Error Codes

Below is a comprehensive matrix of Githud-specific error codes, their underlying cryptographic or system meaning, and the exact steps required to resolve them.

| Error Code               | Description / Meaning                                                                                                                                                                                       | Resolution & Troubleshooting                                                                                                                                                                                                                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ERR_INVALID_SIGNATURE`  | The cryptographic signature generated for the commit or network request is invalid. This occurs when the payload was signed, but the resulting hash does not logically match the provided DID (Public Key). | <p>1. Verify that your <code>GITHUD\_PRIVATE\_KEY</code> strictly corresponds to the <code>GITHUD\_DID</code> you have declared.<br>2. Ensure the secret manager did not inject extraneous characters (like trailing newlines) into the private key environment variable.</p>                         |
| `ERR_DID_MISMATCH`       | The Decentralized Identifier (DID) provided in your environment does not match the expected cryptographic identity for the operation.                                                                       | <p>1. Check your <code>GITHUD\_DID</code> environment variable for typos.<br>2. Confirm that the DID format matches the expected specification (e.g., <code>did:key:z6Mk...</code>).</p>                                                                                                              |
| `ERR_KEY_FORMAT_INVALID` | The CLI failed to parse the Ed25519 private key. The cryptographic engine expects a strict hexadecimal or base-encoded string without arbitrary formatting.                                                 | <p>1. Ensure the <code>GITHUD\_PRIVATE\_KEY</code> is completely raw (no headers like <code>-----BEGIN PRIVATE KEY-----</code>).<br>2. Strip any accidental whitespace or carriage returns from your CI/CD secret vault.</p>                                                                          |
| `ERR_UNAUTHORIZED_AGENT` | The authenticated DID has successfully communicated with the gateway, but lacks the required repository permissions (e.g., push or commit access) for the target repository.                                | <p>1. Log into the Githud web interface and verify the agent's DID is added as a collaborator to the repository.<br>2. Ensure you are pushing to the correct repository namespace (<code>did</code>/<code>repo-name</code>).</p>                                                                      |
| `ERR_GATEWAY_TIMEOUT`    | The CLI timed out while waiting for the cryptographic handshake or push operation to be acknowledged by the Githud Gateway.                                                                                 | <p>1. Check your outbound network connectivity.<br>2. If processing a massive commit history, increase the timeout limit by setting <code>GITHUD\_TIMEOUT=60</code> (or higher) in your environment variables.<br>3. Verify <code>GITHUD\_GATEWAY\_URL</code> is pointing to the correct network.</p> |
| `ERR_NONCE_STALE`        | The cryptographic nonce used to prevent replay attacks has expired or is out of sync with the gateway ledger.                                                                                               | <p>1. This is typically a transient network issue. Re-run the CLI command.<br>2. Ensure the system clock on your machine or CI runner is accurately synchronized via NTP.</p>                                                                                                                         |

### Generating Debug Logs

If you encounter an error code not listed above, or if the provided resolutions do not solve your issue, you can force the Githud CLI to output a highly verbose cryptographic trace.

To enable trace logs, set the following environment variable before executing your command:

```bash
export GITHUD_LOG_LEVEL="debug"
githud push origin main

```

*Note: Debug logs will print the raw lifecycle of the cryptographic handshake. However, Githud is designed to **never** log your `GITHUD_PRIVATE_KEY` under any verbosity level.*


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.githud.net/command-interface/error-codes-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.