Troubleshooting

Start with the symptom below. The CLI’s error and the corresponding request on the phone usually identify the next step.

Pairing has not finished

Check the state saved on this computer:

agentknock pairing status

Reported state	Next step
not paired	Pair the client.
waiting for confirmation	Open Clients on the phone, complete verification for this attempt, then run agentknock pairing finish.
active	Pairing is saved locally. If a command fails, check the client’s state on the phone as described below.

After an interrupted pairing finish, check the status before retrying: the client may already be active. See Finish a pairing.

To abandon a pending attempt, run agentknock pairing abort, then reject that attempt on the phone if it still appears. Aborting removes the local pending record; it does not contact the phone. If verification codes do not match, do not approve the attempt; follow the pairing verification guidance.

The CLI says the client is inactive

agentknock pairing status reads local state without contacting the phone. It can report active even when the phone has suspended or revoked the client.

Open Clients on the phone and select this client. A suspended client can be resumed; wait for the app to confirm it is active before trying again. A revoked client must be paired again. Follow Client details for the action matching its state.

A command keeps waiting

Open Agentknock on the phone and look in the destination for your operation:

Operation	Where to look
Command access, SSH authentication, or Git signing	Requests
Pairing	Clients
Secret upload	Secrets → Incoming uploads

In Requests, use Refresh. If a connection problem appears, open its indicator for details or use Retry. Check whether the request is waiting for you, undergoing AI review, or waiting for the client to confirm a result. Open denied or failed requests for their recorded explanation.

The CLI reports elapsed time every 30 seconds while waiting. A progress message alone does not mean the request failed. If no request arrives, check both devices’ network access and the CLI’s proxy configuration. The secure relay connection uses HTTPS_PROXY or ALL_PROXY, with lowercase variants taking precedence; HTTP_PROXY does not apply.

Requests arrive without a notification

Open Settings → Notifications. Check that notifications are allowed and Requests needing action is enabled in Android’s settings. A hidden Background processing notification does not stop request processing.

If the Delivery section reports incomplete or rejected push registration, the app will retry registration. This is separate from permission to show alerts. You can review requests inside the app while investigating the warning. See Notifications.

A secret or variable cannot be found

Run agentknock secret list to fetch the current secret names and variable names from the phone. Listing requires a connection; it does not read a local cache or return secret values.

Check the spelling in your command, including any variable selector. If the secret was renamed, update commands using the old name. If it was uploaded, open Secrets → Incoming uploads and approve the proposal before using it. A successful upload command confirms that the phone received the proposal, not that it was approved.

Access is denied

Open the request on the phone for the decision and explanation. Then open the secret’s Client access settings and check both its default mode and the override for this client. An explicit override continues to apply when you change the default.

For commands requesting several secrets, a denial for any protected use blocks the whole request. Listing a secret or receiving its public key does not authorize protected values, SSH authentication, or Git signing. Those later operations can require their own decisions.

Stored values or a private key are unavailable

After a restore or device change, the app can retain a secret’s name or public key without the encryption key needed to read its protected contents. Restoring the backed-up files alone cannot recover those contents.

In Secret details, edit an unavailable environment value to supply a replacement, or replace an unavailable SSH private key. If replacement creates a different SSH key, register its new public key with the services that should accept it.

An upload was interrupted

Check Secrets → Incoming uploads before repeating the upload. The proposal may have arrived even if the CLI was interrupted or could not confirm delivery. Review it there if present.

If the app says the proposal is outdated because its target changed, reject it and send a fresh upload against the current secret. See Review an upload and Upload completion.

SSH uses a different key

By default, Agentknock’s temporary agent also offers keys from the inherited SSH agent. Add --no-ssh-passthrough before -- to exclude those agent keys:

agentknock -s deploy --no-ssh-passthrough -- ssh user@server.example

SSH can still use private-key files or an agent selected by its IdentityAgent configuration. Check that configuration if it overrides SSH_AUTH_SOCK; selecting IdentityAgent SSH_AUTH_SOCK makes SSH use the agent supplied by Agentknock. See SSH authentication for the complete behavior.

For Git signing, also check that Git is configured for SSH signatures and that the command requests a signature. See Git signing.

The CLI cannot read its pairing file

The CLI uses pairing.json inside its Agentknock directory, which defaults to $HOME/.agentknock. Run it as the same user who paired it and select the same directory with --agentknock-home or AGENTKNOCK_HOME if you used an override.

If the error specifically reports unsafe file permissions, restrict the file to its owner:

chmod 600 "$HOME/.agentknock/pairing.json"

For a custom directory, use the pairing-file path shown in the error instead.

Do not include the file’s contents in a bug report: it contains pairing credentials.

The problem persists

Use Report a bug for reporting channels and useful diagnostic details. Send suspected vulnerabilities through Security reporting.