# When a step stops you. Find the message or symptom, then check the next step without exposing the value. Use the message you saw to find the next step. When asking for help, share the variable's name, destination, and message. Do not attach the value, a screenshot of a revealed field, or the contents of `.env`. ## The command cannot start ### The command is missing Check that Keyhole is installed and enabled in the VS Code window you are using. Search the Command Palette for `Keyhole: Set a Secret in .env…`. See the [overview](https://jlumbroso.github.io/keyhole-docs/index.html) for current release status and requirements. ### “Open a folder first” Open the local project folder in VS Code, then run the command again. An individual open file is not sufficient. ## Keyhole stopped at the Git check ### “It could not ask git” Check that Git is installed and VS Code's built-in Git extension is enabled. Keyhole has not written the value. Resolve the reported problem, then run the command again. ### “Git tracks it” Keyhole refuses to put a new secret into an already tracked `.env`. Git keeps tracking a file even after you add an ignore rule. From the project folder containing that `.env`, this command stops tracking the file without deleting the local copy: ``` git rm --cached .env ``` Then add `.env` to `.gitignore` and run Keyhole again. If an earlier commit contains a real secret, these changes do not remove that exposure. Revoke or rotate the credential through its service. ### “Git still does not ignore it” Keyhole may have added an ignore rule, but its second check failed. It has not written the secret to `.env`. Review conflicting ignore rules, particularly rules beginning with `!`, and retry once Git reports the file ignored. ### “A git repository that VS Code's Git extension did not open” VS Code did not return a usable repository, but Keyhole found a `.git` marker in the project folder or a folder above it. Keyhole refuses to write because it cannot check the tracking and ignore rules. Run `git status` in a terminal in that folder to see why, or inspect VS Code's Git output. Git may report an ownership warning. Resolve the cause before retrying; do not dismiss a warning merely to make the message disappear. ### The folder does not use Git If VS Code returns no repository and Keyhole finds no `.git` marker in the folder or any parent folder, it treats the folder as having no repository and permits the write. The tracking and ignore checks do not run on that path. If you later enable Git or copy the project elsewhere, make sure `.env` is ignored before adding project files to a commit. ## The name or value was not accepted ### The name is not accepted Use the exact name expected by the project, in capital letters, digits, and underscores, starting with a letter. Keyhole also refuses some names that change how programs execute, such as `PATH` and `NODE_OPTIONS`. Do not invent a different name merely to bypass a refusal; the program may not recognize it. ### “The value has more than one line” This version writes single-line values. A private-key file or certificate may require a different setup. Follow that service's instructions; do not remove line breaks merely to make Keyhole accept the value. ### “It cannot be written safely in one line” Keyhole rejects some combinations of quotation marks and characters a program could expand when loading the file. Keep the credential unchanged and use the service or framework's documented configuration method. ## Something is wrong after saving ### “Wrote … but reading it back did not match” Keyhole did write the file but could not verify the result. Do not treat this as success or repeatedly submit more values. Inspect the destination locally; ask for help using the message and variable name without sharing the file. ### Keyhole saved it, but my program still fails 1. Confirm the variable name and the project folder you selected. 2. Confirm that the program reads that folder's `.env`. A file write alone does not configure the program to load it. 3. Restart the relevant program if it loads settings at startup. A local file does not update a hosted service's environment. 4. Check that the credential has the right type and permissions for the operation, and is still valid at its provider. Ask for a result such as “setting present” or “connection succeeded,” without printing the value. Avoid an environment dump or a copy of the configuration file. ### An older value is still in the file Keyhole retains earlier assignments. It appends the newer one and identifies the superseded line in its comment. After the new value works, you may remove the old line locally. Removing a line does not revoke the credential at its service. ### What is a keyprint? A keyprint is a recognition marker used in messages and logs. It contains a recognized public prefix, when there is one, and a short hash. Values at least 32 characters long also show their last four characters. It is not the complete credential. ## A real value entered the conversation Use the provider's instructions to revoke or rotate it. Adding a file-read rule afterward does not undo the exposure. Configure your assistant's [file protections](https://jlumbroso.github.io/keyhole-docs/keeping-secrets-out-of-the-conversation.html) before entering the replacement through Keyhole. ## Chapter notes **When asking for help** Share the variable name and the message. Leave out the value, .env contents, and revealed screenshots. **Local settings** Writing a local .env does not configure a hosted service. Keyhole 0.1.0 · previews labeled separately. Updated 24 October 2026. [Online chapter](https://jlumbroso.github.io/keyhole-docs/troubleshooting.html). [Source reference](https://github.com/jlumbroso/keyhole/blob/main/docs/manual/content/troubleshooting.html). Source access currently requires a repository invitation.