---
description: Diagnose ghtkn problems and known limitations. Use when ghtkn or the gh wrapper misbehaves, a token is expired (401), the device flow code is not shown, or hitting Packages API / cross-user repo limits.
---

# Troubleshooting

> [!WARNING]
> The token `ghtkn get` outputs is a live secret. Never print, echo, log, or include it in your output, a chat message, a commit, or an issue/PR, and don't run `ghtkn get` (including `-f json`) just to display or inspect it. Diagnosing a problem is not a reason to reveal the token: when you share the output of the commands below, redact it. See [Do not leak the access token](token-management.md#do-not-leak-the-access-token).

## ghtkn doesn't work well

1. Check environment variables, ghtkn version, etc.

```sh
ghtkn info
```

If `ghtkn info` command isn't found or the version isn't latest, please upgrade ghtkn to the latest version.

With the agent backend, `ghtkn info` also reports the agent's own version under `agent.version`, plus the agent protocol versions both sides speak.
Upgrading ghtkn doesn't upgrade a running agent, so if `agent.version` is older than the top level `version`, restart the agent: `ghtkn agent stop`, then start and unlock it again.

2. Check the token and expiration date.

```sh
ghtkn get -f json [<app name>]
```

This output contains the access token itself, so treat it as a secret: read the expiration date from it, but don't paste it anywhere unredacted.

3. Check the access token is available.

```sh
ghtkn exec -e GH_TOKEN -- gh auth status
```

Please confirm the prefix of the token is `ghu_`.
If the prefix isn't `ghu_`, another type of token is used.

```
github.com
  o Logged in to github.com account suzuki-shunsuke (GH_TOKEN)
  - Active account: true
  - Git operations protocol: https
  - Token: ghu_************************************
```

4. Check the access token is valid using curl.

```sh
ghtkn exec -- sh -c 'curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/user'
```

The single quotes matter: `$GITHUB_TOKEN` has to be expanded by the command, not by your shell, so the token never becomes part of the command line.

5. Check the configuration file is correct.

## The wrapper of `gh` command doesn't work well

1. [Check if `ghtkn` works well](#ghtkn-doesnt-work-well)
1. Check if the wrapper is invoked correctly.

```sh
command -v gh
```

1. Check if another access token like personal access token is set
1. Check if the correct app is used

```sh
gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  /user/installations
```

If the response `installations` is empty, the app is either not installed or not installed on any account you have access to.

```json
{
  "total_count": 0,
  "installations": []
}
```

If a wrong app is used, please specify the correct app via the environment variable `GHTKN_APP`.

1. Add the debug log to the wrapper.

e.g.

```sh
if [ -n "${GH_TOKEN:-}" ] || [ -n "${GITHUB_TOKEN:-}" ]; then
  echo "[WARN] skip ghtkn because GH_TOKEN or GITHUB_TOKEN is set" >&2 # Add the debug log
  exec /opt/homebrew/bin/gh "$@"
fi

exec ghtkn exec -e GH_TOKEN --log-level debug -- /opt/homebrew/bin/gh "$@" # ghtkn logs which app it uses
```

## ghtkn returns an expired token (401)

If `ghtkn get` returns an expired token, you can renew it by running `ghtkn auth`.

```sh
ghtkn auth
```

## The device flow asks the verification code, but the code isn't shown anywhere

When ghtkn is run in the background process, the verification code is not displayed in the terminal.
In that case, you need to:

1. Cancel the process `A`
1. Run `ghtkn auth [app for process A]` manually to renew the access token
1. Re-run the process `A`

As of ghtkn v0.4.0, only `ghtkn auth` starts the device flow, so this kind of issue no longer happens. When the token expires, you need to run `ghtkn auth` to renew it.

## A browser opens when using tools like cmux and warp

When using [cmux](https://github.com/manaflow-ai/cmux) and [warp](https://github.com/warpdotdev/warp), ghtkn may open a browser on its own.
Worse, the one-time code isn't shown anywhere, so you can't complete the device flow and have to close the browser tab.

As of ghtkn v0.4.0, only `ghtkn auth` starts the device flow, so this kind of issue no longer happens. When the token expires, you need to run `ghtkn auth` to renew it.

## Limitations

ghtkn obtains a user access token, but unfortunately it has some limitations so a personal access token is required for some operations.

1. Packages API requires a classic personal access token
1. It's difficult to write other user's repositories

### Packages API requires a classic personal access token

- https://docs.github.com/en/rest/packages/packages?apiVersion=2026-03-10
- > To use the REST API to manage GitHub Packages, you must authenticate using a personal access token (classic).

### GitHub CLI's `--attach` doesn't work

Probably `--attach` doesn't work with user access tokens.

- https://github.com/cli/cli/issues/14309
- https://github.com/cli/cli/issues/14495

### It's difficult to write other user's repositories

To write other users' repositories, a GitHub App installed on the target repository and its client id is required.
It's hard to ask others to install a GitHub App on their repository and share the client id with you.

For instance, it's difficult to create pull requests to other users' repositories by `gh pr create` command.
In that case, the `--web` option of `gh pr create` is useful.