Skip to Content
APIs & ToolsCommand Line Interface (CLI)Troubleshooting

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:

finqu sign-in

If you’re using API credentials directly:

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:

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

Or provide credentials directly:

finqu sign-in --key $FINQU_API_KEY --secret $FINQU_API_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:
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 watch instead of repeatedly running finqu theme deploy

File Sync Issues

Files not syncing correctly

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

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:

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:
finqu theme deploy --config /path/to/finqu.config.json

Wrong environment being used

Specify the environment explicitly:

finqu theme deploy --env production
finqu theme deploy --env development

Check your finqu.config.json to see which environments are configured.

Debugging

Enable verbose logging

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

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:

finqu --version

Update if needed:

npm install -g @finqu/cli@latest

Getting Help

If you’re still experiencing issues:

  1. Check the Overview page for general information
  2. Review the specific command documentation:
  3. Contact Finqu Support
  4. Open an issue on GitHub