# Troubleshooting

Common issues and solutions when working with the Finqu CLI.

## Authentication Errors

### "Authentication failed" or "Invalid credentials"

**Solution:** Re-authenticate using `finqu sign-in`:

```bash
finqu sign-in
```

If you're using API credentials directly:

```bash
finqu sign-in --key YOUR_API_KEY --secret YOUR_API_SECRET
```

### "Token expired" errors

The CLI automatically refreshes tokens when they expire. If you're seeing persistent token expiration errors:

1. Run `finqu sign-in` again to refresh your authentication
2. Check that your system clock is synchronized (token validation depends on accurate timestamps)

### Authentication not working in CI/CD

For headless environments (CI/CD pipelines), use environment variables or provide credentials directly:

```bash
export FINQU_API_CLIENT_ID=your_key
export FINQU_API_CLIENT_SECRET=your_secret
finqu sign-in
```

Or provide credentials directly:

```bash
finqu sign-in --key $FINQU_API_CLIENT_ID --secret $FINQU_API_CLIENT_SECRET
```

## Permission Errors

### "You don't have permission to access this theme"

**Possible causes:**

- Your account doesn't have access to the theme
- The theme ID in your configuration is incorrect
- Your API credentials don't have the necessary permissions

**Solutions:**

1. Verify you have access to the theme in the Finqu admin panel
2. Re-run `finqu theme configure` to select the correct theme
3. Check with your account administrator about API permissions

## API Errors

### "API request failed" or "Network error"

**Solutions:**

1. Check your internet connection
2. Verify the `resourceUrl` in your configuration file is correct
3. Check if the Finqu API is experiencing downtime
4. Use the `-v` or `--verbose` flag to get detailed error output:

```bash
finqu theme deploy -v
```

### Rate limiting errors

If you're making many rapid requests, you might hit rate limits. The CLI will automatically retry with exponential
backoff. If issues persist:

- Reduce the frequency of your requests
- Use `finqu theme dev` for local iteration and only deploy when needed

## Theme Dev Issues

### `finqu-theme-dev` not found

If `finqu theme dev` reports that `finqu-theme-dev` is missing, install it first:

- Follow the installation guide: [/apis-and-tools/theme-dev/installation](/apis-and-tools/theme-dev/installation)
- Ensure the binary is available on your `PATH`

### Theme dev authentication errors

`finqu theme dev` automatically checks authentication and runs `finqu-theme-dev auth` when credentials are missing. If
authentication still fails:

1. Run `finqu theme dev` again and complete the auth prompts
2. Run `finqu-theme-dev auth` directly to verify your store URL and channel API key
3. Confirm your credentials file exists at `~/.finqu-theme-dev/credentials.json`

## File Sync Issues

### Files not syncing correctly

**Solution:** Use `--clean` to ensure remote files match local files:

```bash
finqu theme deploy --clean
```

This removes remote files that don't exist locally, ensuring your remote theme matches your local directory.

### Protected files not uploading

By default, `config/settings_data.json` and `config/.draft` are protected from upload to prevent overwriting theme
settings. If you need to upload these:

```bash
finqu theme deploy --force
```

> **Warning:** Using `--force` can overwrite theme settings made in the backend theme editor. Use with caution.

### Files uploading but changes not visible

After deploying, the server compiles assets automatically. If changes aren't visible:

1. Wait a few seconds for compilation to complete
2. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
3. Check browser cache settings
4. Verify you're viewing the correct theme version

## Configuration Issues

### "Configuration file not found"

**Solutions:**

1. Run `finqu theme configure` to create the configuration file
2. Ensure you're in the correct directory
3. Specify the config file path explicitly:

```bash
finqu theme deploy --config /path/to/.env
```

## Debugging

### Enable verbose logging

Use the `-v` or `--verbose` flag to get detailed output:

```bash
finqu theme deploy -v
finqu sign-in -v
```

This shows:

- API requests and responses
- File operations
- Configuration values being used
- Detailed error messages

### Check CLI version

Ensure you're using a recent version:

```bash
finqu --version
```

Update if needed:

```bash
npm install -g @finqu/cli@latest
```

## Getting Help

If you're still experiencing issues:

1. Check the [Overview](./overview) page for general information
2. Review the specific command documentation:
   - [Authentication](./authentication)
   - [Theme Commands](./theme)
   - [Configuration](./configuration)
3. Contact [Finqu Support](mailto:contact@finqu.com)
4. Open an issue on [GitHub](https://github.com/finqu/cli/issues)