Skip to main content

​
Installation Issues

Problem: CLI command is not recognized.Solution: Use bunx or npx to run the CLI:
bunx readonly sync
# or
npx readonly sync
The package is installed locally, not globally.
Problem: Cannot import from @readonly/client.Solutions:
  1. Make sure the package is installed: 
    bun add @readonly/client
  2. Run sync at least once to generate files: 
    bunx readonly sync
  3. Check that node_modules/_generated/readonly/ exists
Problem: TypeScript doesn’t recognize types from ReadOnly.Solutions:
  1. Run sync to generate types: 
    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: 
    {
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

​
Authentication Issues

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)
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_
Make sure you're using the right project's API key 4. Try regenerating the API key from the dashboard
</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
  1. Regenerate types: 
    bunx readonly codegen
  2. Restart your TypeScript server
  3. If types are still wrong, file a bug report with your JSON structure
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:
{
  "items": [1, "hello", true]
}
Generates:
{
  items: (string | number | boolean)[];
}
Solution: Keep arrays homogeneous for better type inference.
Problem: node_modules/_generated/readonly/ doesn’t exist.Solutions:
  1. Run sync at least once: 
    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/

​
Build & Production Issues

Problem: Application can’t find readonly files in production.Solutions:
  1. Run sync before building:
    package.json
    {
  "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: 
    RUN npx readonly sync
Problem: Files missing after deployment.Solutions:
  1. Include sync in your build process (see above)
  2. For serverless, run sync in postinstall:
    package.json
    {
  "scripts": {
    "postinstall": "readonly sync"
  }
}
  3. For Docker, sync during image build, not runtime
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 @readonly/client is in dependencies, not devDependencies
  3. Check CI logs for specific error messages

​
File Content Issues

Problem: Dashboard rejects your JSON file.Solutions:
  1. Validate JSON syntax: 
    cat yourfile.json | jq
  2. Root must be an object: 
    // ✅ Valid
{ "items": [1, 2, 3] }

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

// ❌ Invalid (primitive at root)
"hello"
  3. Remove trailing commas: 
    // ❌ Invalid
{ "key": "value", }

// ✅ Valid
{ "key": "value" }
Problem: File size exceeds the maximum limit of 10MBSolutions:
  1. Split large files into smaller ones
  2. Remove unnecessary data
  3. Minify JSON (remove whitespace): 
    cat yourfile.json | jq -c > minified.json
  4. Consider storing large data elsewhere (S3, database, etc.)
Problem: Dashboard rejects file name.Solutions: File names must match: ^[a-zA-Z0-9_-]+$
# ✅ 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

​
Development Issues

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
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

​
Getting Help

If you’re still experiencing issues:

Email Support

Send us an email with details about your issue.

GitHub Issues

Report bugs or request features on GitHub.

Documentation

Review the documentation for more details.

Dashboard

Check your project settings in the dashboard.

​
Diagnostic Commands

Run these commands to help diagnose issues: 
# 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 @readonly/client
Include output from these commands when reporting issues.