Troubleshooting

Installation Issues

Command not found: readonly

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.

Module not found: @readonlystore/client

Problem: Cannot import from @readonlystore/client.Solutions:

Make sure the package is installed:
bun add @readonlystore/client
Run sync at least once to generate files:
bunx readonly sync
Check that node_modules/_generated/readonly/ exists

TypeScript cannot find types

Problem: TypeScript doesn’t recognize types from ReadOnly.Solutions:

Run sync to generate types:
bunx readonly sync
Restart your TypeScript server:
- VS Code: Press Cmd+Shift+P → “TypeScript: Restart TS Server”

Check tsconfig.json includes node_modules:

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

Authentication Issues

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)

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_

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

Regenerate types:
bunx readonly codegen
Restart your TypeScript server
If types are still wrong, file a bug report with your JSON structure

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:

{
  "items": [1, "hello", true]
}

Generates:

{
  items: (string | number | boolean)[];
}

Solution: Keep arrays homogeneous for better type inference.

Cannot find generated files

Problem: node_modules/_generated/readonly/ doesn’t exist.Solutions:

Run sync at least once:
bunx readonly sync
Check that sync completed successfully
Verify READONLY_OUTPUT_DIR environment variable (if set)
Check file permissions on node_modules/

Build & Production Issues

Files not found in production

Problem: Application can’t find readonly files in production.Solutions:

Run sync before building:

package.json

{
  "scripts": {
    "build": "readonly sync && next build"
  }
}

Make sure READONLY_API_KEY is set in production environment
Check that cache directory is included in your build
For Docker, add sync to Dockerfile:
RUN npx readonly sync

Cache cleared after deploy

Problem: Files missing after deployment.Solutions:

Include sync in your build process (see above)

For serverless, run sync in postinstall:

package.json

{
  "scripts": {
    "postinstall": "readonly sync"
  }
}

For Docker, sync during image build, not runtime

CI/CD sync failing

Problem: Sync fails in CI/CD pipeline.Solutions:

Add READONLY_API_KEY to CI secrets:
- GitHub: Repository Secrets
- GitLab: CI/CD Variables
- CircleCI: Environment Variables
Make sure @readonlystore/client is in dependencies, not devDependencies
Check CI logs for specific error messages

File Content Issues

JSON validation failed

Problem: Dashboard rejects your JSON file.Solutions:

Validate JSON syntax:
cat yourfile.json | jq

Root must be an object:

// ✅ Valid
{ "items": [1, 2, 3] }

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

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

Remove trailing commas:

// ❌ Invalid
{ "key": "value", }

// ✅ Valid
{ "key": "value" }

File size exceeded

Problem: File size exceeds the maximum limit of 10MBSolutions:

Split large files into smaller ones
Remove unnecessary data

Minify JSON (remove whitespace):

cat yourfile.json | jq -c > minified.json

Consider storing large data elsewhere (S3, database, etc.)

Invalid file name

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

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

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

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 @readonlystore/client

Include output from these commands when reporting issues.

Getting Started

Client

Help

Installation Issues

Authentication Issues

Build & Production Issues

File Content Issues

Development Issues

Getting Help

Email Support

GitHub Issues

Documentation

Dashboard

Diagnostic Commands

​Installation Issues

​Authentication Issues

​Build & Production Issues

​File Content Issues

​Development Issues

​Getting Help

Email Support

GitHub Issues

Documentation

Dashboard

​Diagnostic Commands

Installation Issues

Authentication Issues

Build & Production Issues

File Content Issues

Development Issues

Getting Help

Diagnostic Commands