> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enkryptify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Common issues you may encounter when using the Enkryptify CLI and how to resolve them.

## Authentication

These errors occur when the CLI cannot verify your identity.

<AccordionGroup>
  <Accordion title="Not authenticated">
    **Error:** `Not authenticated.`

    No valid credentials were found on this machine. This usually means you haven't logged in yet or your credentials were cleared.

    ```bash theme={"dark"}
    ek login
    ```
  </Accordion>

  <Accordion title="Session expired or invalid credentials">
    **Error:** `Authentication failed.`

    Your session has expired or your stored credentials are no longer valid. Re-authenticate to get a fresh token.

    ```bash theme={"dark"}
    ek login
    ```

    If the problem persists, force a full re-authentication:

    ```bash theme={"dark"}
    ek login --force
    ```
  </Accordion>

  <Accordion title="API returns 401 Unauthorized">
    **Error:** `Authentication failed.` (during a command like `run` or `secret list`)

    The API rejected your credentials. This typically happens when your token expires mid-session.

    ```bash theme={"dark"}
    ek login
    ```
  </Accordion>
</AccordionGroup>

### Where are credentials stored?

The CLI stores your authentication token in the operating system's credential store:

* **macOS**: Keychain
* **Linux**: Secret Service (GNOME Keyring) or KWallet
* **Windows**: Credential Manager

### Headless environments

In environments without a credential store (CI runners, containers, minimal servers), set the `EK_TOKEN` environment variable instead. The CLI reads this variable automatically and skips the credential store.

For more details on the login flow, see the [`login` command reference](/cli/commands#login).

***

## Configuration

These errors occur when the CLI cannot find or read your project configuration.

<AccordionGroup>
  <Accordion title="No project configured for this directory">
    **Error:** `No project configured for this directory.`

    No Enkryptify configuration was found for the current directory or any parent directory. Link your project first:

    ```bash theme={"dark"}
    ek configure
    ```
  </Accordion>

  <Accordion title="Configuration file is corrupted or contains invalid JSON">
    **Error:** `Configuration file is corrupted.` or `Configuration file contains invalid JSON.`

    The configuration file could not be parsed. Delete it and re-configure:

    ```bash theme={"dark"}
    rm ~/.enkryptify/config.json
    ek configure
    ```
  </Accordion>

  <Accordion title="Configuration is incomplete">
    **Error:** `Your project configuration is incomplete.`

    The configuration file is missing required fields (workspace, project or environment). Re-run the setup wizard to fill them in:

    ```bash theme={"dark"}
    ek configure
    ```
  </Accordion>

  <Accordion title="Project file is invalid">
    **Error:** `The project file ".enkryptify.json" contains invalid JSON.` or `The project file ".enkryptify.json" is missing required fields.`

    A committed `.enkryptify.json` file was found but could not be used. It must contain a JSON object with non-empty `workspace`, `project` and `environment` fields, each a slug or an id:

    ```json .enkryptify.json theme={"dark"}
    {
      "workspace": "my-workspace",
      "project": "backend",
      "environment": "10af8e49-453e-477b-b181-12b7ad95c8f2"
    }
    ```

    See the [project configuration file](/cli/commands#project-configuration-file) reference for details.
  </Accordion>

  <Accordion title="Permission denied">
    **Error:** `Cannot access the configuration file.`

    The CLI cannot read or write the configuration directory.

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={"dark"}
        chmod 755 ~/.enkryptify
        ```
      </Tab>

      <Tab title="Windows">
        Adjust folder permissions on `%USERPROFILE%\.enkryptify` or run your terminal as Administrator.
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

### Config file location

The configuration is stored at `~/.enkryptify/config.json`. Each entry maps a directory path to a workspace, project and environment:

```json theme={"dark"}
{
  "setups": {
    "/path/to/your/project": {
      "workspace_slug": "my-workspace",
      "project_slug": "my-project",
      "environment_id": "env-id"
    }
  }
}
```

A committed `.enkryptify.json` file in your project takes precedence over these setups. See the [project configuration file](/cli/commands#project-configuration-file) reference.

For more details on the configure flow, see the [`configure` command reference](/cli/commands#configure).

***

## Secrets

<Warning>
  The `ek secret` commands are **deprecated** and may be removed in a future release. Manage secrets through the [dashboard](https://app.enkryptify.com) instead.
</Warning>

These errors occur when creating or updating secrets.

<AccordionGroup>
  <Accordion title="Invalid secret name">
    **Error:** `Invalid secret name.`

    Secret names can only contain:

    * Letters: `A-Z`, `a-z`
    * Numbers: `0-9`
    * Underscore: `_`
    * Hyphen: `-`

    Names must be between 2 and 48 characters long.

    ```bash theme={"dark"}
    # Valid
    ek secret create DATABASE_URL "postgres://..."
    ek secret create my-api-key "sk_live_..."

    # Invalid
    ek secret create "my secret" "value"    # spaces not allowed
    ek secret create "a" "value"            # too short
    ```
  </Accordion>

  <Accordion title="Empty secret value">
    **Error:** `Secret value cannot be empty.`

    Provide a non-empty value. Use quotes for values that contain spaces or special characters:

    ```bash theme={"dark"}
    ek secret create API_KEY "my-secret-value"
    ```
  </Accordion>
</AccordionGroup>

For more details on managing secrets, see the [`secret` command reference](/cli/commands#secret-create).

***

## Network

These errors occur when the CLI cannot reach the Enkryptify API.

<AccordionGroup>
  <Accordion title="Could not connect to the Enkryptify API">
    **Error:** `Could not connect to the Enkryptify API.`

    The API server is unreachable. Common causes:

    1. **No internet connection**: verify your network is working
    2. **Firewall or proxy**: ensure `api.enkryptify.com` (port 443) is not blocked
    3. **VPN**: some VPNs block outbound traffic; try disconnecting temporarily
    4. **Self-hosted**: verify the `API_BASE_URL` environment variable points to the correct server

    As a workaround, use the `--offline` flag to run with previously cached secrets:

    ```bash theme={"dark"}
    ek run --offline -- npm start
    ```

    <Note>
      `--offline` only works if you have run the command at least once while online so that secrets are cached.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Debug mode

If you need more detail about what the CLI is doing, enable debug logging by setting one of these environment variables:

```bash theme={"dark"}
EK_DEBUG=1 ek run -- npm start
# or
EK_VERBOSE=1 ek run -- npm start
```

This prints additional diagnostic information to stderr, which can help you or the Enkryptify support team identify the root cause of an issue.