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

# Troubleshooting

> Common issues and solutions for ReadOnly

## Installation Issues

<AccordionGroup>
  <Accordion title="Command not found: readonly">
    **Problem:** CLI command is not recognized.

    **Solution:** Use `bunx` or `npx` to run the CLI:

    ```bash theme={null}
    bunx readonly sync
    # or
    npx readonly sync
    ```

    The package is installed locally, not globally.
  </Accordion>

  <Accordion title="Module not found: @readonlystore/client">
    **Problem:** Cannot import from `@readonlystore/client`.

    **Solutions:**

    1. Make sure the package is installed:
       ```bash theme={null}
       bun add @readonlystore/client
       ```

    2. Run sync at least once to generate files:
       ```bash theme={null}
       bunx readonly sync
       ```

    3. Check that `node_modules/_generated/readonly/` exists
  </Accordion>

  <Accordion title="TypeScript cannot find types">
    **Problem:** TypeScript doesn't recognize types from ReadOnly.

    **Solutions:**

    1. Run sync to generate types:
       ```bash theme={null}
       bunx readonly sync
       ```

    2. Restart your TypeScript server:
       * VS Code: Press `Cmd+Shift+P` → "TypeScript: Restart TS Server"

    3. Check `tsconfig.json` includes `node_modules`:
       ```json theme={null}
       {
         "compilerOptions": {
           "moduleResolution": "node"
         }
       }
       ```
  </Accordion>
</AccordionGroup>

***

## Authentication Issues

<AccordionGroup>
  <Accordion title="Missing READONLY_API_KEY">
    **Problem:** `Missing READONLY_API_KEY environment variable` **Solutions:** 1. Set the environment variable:
    `bash export READONLY_API_KEY=ro_your_key_here ` 2. Or create a `.env` file: `bash
        		READONLY_API_KEY=ro_your_key_here ` 3. Make sure your `.env` loader is configured (if using one)
  </Accordion>

  <Accordion title="Invalid API key">
    **Problem:** `Invalid API key` error when syncing. **Solutions:** 1. Verify your API key is correct (copy from
    dashboard) 2. Check for whitespace or special characters: \`\`\`bash echo \$READONLY\_API\_KEY # Should start with ro\_

    ````3. Make sure you're using the right project's API key 4. Try regenerating the API key from the dashboard theme={null}
    </Accordion>

    <Accordion title="Project not found">
    **Problem:** API key is valid but project doesn't exist. **Solutions:** 1. Check that the project still exists
    in the dashboard 2. Verify you're using the correct API key (not from a different project) 3. Make sure the
    project wasn't deleted
    </Accordion>

    </AccordionGroup>

    ---

    ## Sync Issues

    <AccordionGroup>
    <Accordion title="Network timeout">
    **Problem:** Sync times out or hangs. **Solutions:** 1. Check your internet connection 2. The CLI will
    automatically retry with exponential backoff 3. If behind a corporate firewall, check proxy settings 4. Verify
    you can access `https://api.readonly.store`
    </Accordion>

    <Accordion title="Files not updating">
    **Problem:** Local files don't match dashboard after sync. **Solutions:** 1. Clear the cache and re-sync:
    ```bash rm -rf node_modules/.cache/readonly rm -rf node_modules/_generated/readonly bunx readonly sync ``` 2.
    Check that sync completed successfully (look for success message) 3. Verify you're editing the correct project
    in the dashboard 4. Restart your development server after syncing
    </Accordion>

    <Accordion title="Sync is very slow">
    **Problem:** Sync takes a long time to complete. **Possible causes:** - Large files (close to 10MB limit) - Many
    files in project - Slow internet connection **Solutions:** 1. Split large files into smaller ones 2. Remove
    unused files from the project 3. Use watch mode (`readonly dev`) to keep files in sync instead of repeated syncs
    </Accordion>

    <Accordion title="Watch mode disconnects">
    **Problem:** Watch mode keeps disconnecting. **Solutions:** 1. The CLI automatically reconnects with exponential
    backoff 2. Check your internet connection stability 3. If behind a VPN, check for WebSocket blocking 4. Look for
    error messages in the console for more details
    </Accordion>

    </AccordionGroup>

    ---

    ## Type Generation Issues

    <AccordionGroup>
    <Accordion title="Generated types are incorrect">
    **Problem:** TypeScript types don't match JSON structure.

    **Solutions:**
    1. Make sure your JSON is valid:
       ```bash
       cat node_modules/.cache/readonly/yourfile.json | jq
    ````

    2. Regenerate types:
       ```bash theme={null}
       bunx readonly codegen
       ```

    3. Restart your TypeScript server

    4. If types are still wrong, file a bug report with your JSON structure
  </Accordion>

  <Accordion title="Type inference for arrays">
    **Problem:** Array types are too broad or inaccurate.

    **Explanation:** ReadOnly infers types from the actual values in your JSON. Mixed arrays will have union types.

    **Example:**

    ```json theme={null}
    {
      "items": [1, "hello", true]
    }
    ```

    Generates:

    ```typescript theme={null}
    {
      items: (string | number | boolean)[];
    }
    ```

    **Solution:** Keep arrays homogeneous for better type inference.
  </Accordion>

  <Accordion title="Cannot find generated files">
    **Problem:** `node_modules/_generated/readonly/` doesn't exist.

    **Solutions:**

    1. Run sync at least once:
       ```bash theme={null}
       bunx readonly sync
       ```

    2. Check that sync completed successfully

    3. Verify `READONLY_OUTPUT_DIR` environment variable (if set)

    4. Check file permissions on `node_modules/`
  </Accordion>
</AccordionGroup>

***

## Build & Production Issues

<AccordionGroup>
  <Accordion title="Files not found in production">
    **Problem:** Application can't find readonly files in production.

    **Solutions:**

    1. Run sync before building:
       ```json package.json theme={null}
       {
         "scripts": {
           "build": "readonly sync && next build"
         }
       }
       ```

    2. Make sure `READONLY_API_KEY` is set in production environment

    3. Check that cache directory is included in your build

    4. For Docker, add sync to Dockerfile:
       ```dockerfile theme={null}
       RUN npx readonly sync
       ```
  </Accordion>

  <Accordion title="Cache cleared after deploy">
    **Problem:** Files missing after deployment.

    **Solutions:**

    1. Include sync in your build process (see above)

    2. For serverless, run sync in postinstall:
       ```json package.json theme={null}
       {
         "scripts": {
           "postinstall": "readonly sync"
         }
       }
       ```

    3. For Docker, sync during image build, not runtime
  </Accordion>

  <Accordion title="CI/CD sync failing">
    **Problem:** Sync fails in CI/CD pipeline.

    **Solutions:**

    1. Add `READONLY_API_KEY` to CI secrets:
       * GitHub: Repository Secrets
       * GitLab: CI/CD Variables
       * CircleCI: Environment Variables

    2. Make sure `@readonlystore/client` is in `dependencies`, not `devDependencies`

    3. Check CI logs for specific error messages
  </Accordion>
</AccordionGroup>

***

## File Content Issues

<AccordionGroup>
  <Accordion title="JSON validation failed">
    **Problem:** Dashboard rejects your JSON file.

    **Solutions:**

    1. Validate JSON syntax:
       ```bash theme={null}
       cat yourfile.json | jq
       ```

    2. Root must be an object:
       ```json theme={null}
       // ✅ Valid
       { "items": [1, 2, 3] }

       // ❌ Invalid (array at root)
       [1, 2, 3]

       // ❌ Invalid (primitive at root)
       "hello"
       ```

    3. Remove trailing commas:
       ```json theme={null}
       // ❌ Invalid
       { "key": "value", }

       // ✅ Valid
       { "key": "value" }
       ```
  </Accordion>

  <Accordion title="File size exceeded">
    **Problem:** `File size exceeds the maximum limit of 10MB`

    **Solutions:**

    1. Split large files into smaller ones

    2. Remove unnecessary data

    3. Minify JSON (remove whitespace):
       ```bash theme={null}
       cat yourfile.json | jq -c > minified.json
       ```

    4. Consider storing large data elsewhere (S3, database, etc.)
  </Accordion>

  <Accordion title="Invalid file name">
    **Problem:** Dashboard rejects file name.

    **Solutions:**
    File names must match: `^[a-zA-Z0-9_-]+$`

    ```bash theme={null}
    # ✅ Valid
    documents
    my-config
    user_data
    v1_2_3

    # ❌ Invalid
    my.config      # dots not allowed
    user data      # spaces not allowed
    config!        # special chars not allowed
    ```
  </Accordion>
</AccordionGroup>

***

## Development Issues

<AccordionGroup>
  <Accordion title="Hot reload not working">
    **Problem:** Changes don't reflect in development. **Solutions:** 1. Use watch mode: `bash bunx readonly dev
        		` 2. Restart your dev server after syncing 3. Clear build cache and restart: `bash rm -rf .next # for
        		Next.js rm -rf dist # for Vite `
  </Accordion>

  <Accordion title="Import errors after updating files">
    **Problem:** TypeScript errors after updating file structure. **Solutions:** 1. Restart TypeScript server 2.
    Regenerate types: `bash bunx readonly codegen ` 3. If structure changed significantly, update your imports
  </Accordion>
</AccordionGroup>

***

## Getting Help

If you're still experiencing issues:

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:contact@readonly.store">
    Send us an email with details about your issue.
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/readonlystore/code/issues">
    Report bugs or request features on GitHub.
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Review the documentation for more details.
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://readonly.store">
    Check your project settings in the dashboard.
  </Card>
</CardGroup>

***

## Diagnostic Commands

Run these commands to help diagnose issues:

```bash theme={null}
# Check if CLI is installed
bunx readonly --help

# Verify environment variables
echo $READONLY_API_KEY
echo $READONLY_API_URL

# Check cache directory
ls -la node_modules/.cache/readonly/

# Check generated files
ls -la node_modules/_generated/readonly/

# Validate JSON
cat node_modules/.cache/readonly/yourfile.json | jq

# Test connectivity
curl https://api.readonly.store

# Check package installation
npm list @readonlystore/client
```

Include output from these commands when reporting issues.