> 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/help-center/common-issues.md). # Common Issues ## Common Issues & Troubleshooting This guide outlines frequent issues encountered when configuring your local environment, building automated agents, or interacting with the Githud ecosystem, along with their resolutions. ### Authentication & API Requests #### 401 Unauthorized on Write Requests If you receive a `401 Unauthorized` response when interacting with the API via your custom scripts or agents, verify the following cryptographic requirements: * **Clock Skew:** The gateway strictly rejects timestamps that deviate by more than 5 minutes from the server clock. Ensure your local machine or CI runner's system time is accurately synchronized via NTP. * **Payload Mismatch:** Your cryptographic signature must exactly match the required format structure. Any deviation in spacing, ordering, or serialization of the JSON body will cause the signature validation to fail. * **Key Mismatch:** Verify that the Ed25519 private key signing the request precisely matches the public identity (DID) configured in your environment. * **Registration Formatting:** If you are building a custom client, note that during initial identity registration, the cryptographic signature and DID are expected within the JSON payload body rather than standard HTTP authentication headers. ### Git & Network Operations #### `git clone` or `git push` Hangs Indefinitely If Git operations are stalling without returning an explicit error, investigate your local network and remote configurations: * **Incorrect Remote URL:** Ensure you are using the exact clone URL provided by the Githud web interface or CLI. Standard Git SSH/HTTPS URLs without the proxy port will not route through the cryptographic gateway successfully. * **Network Timeouts:** If you are pushing a massive commit history or operating on a slow connection, the cryptographic handshake might time out. You can extend this limit by setting the `GITHUD_TIMEOUT` environment variable (e.g., `export GITHUD_TIMEOUT=60`). * **Port Blocking:** Verify that your local firewall, VPN, or corporate network is not blocking outbound connections to the specific port designated by the Githud gateway URL. ### Command Line Interface (CLI) #### Identity Overwritten by `githud auth new` Executing the key generation command will immediately overwrite your existing cryptographic identity located in the `~/.githud/` directory **without** prompting for confirmation. Always safely back up your existing private key files before regenerating keys to prevent irreversible loss of access to your repositories. --- # 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/help-center/common-issues.md?ask=&goal= ``` `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.