Skip to main content
Reference

uc-bq Troubleshooting

Overview​

Errors from uc-bq fall into a handful of families: the package did not install cleanly, Google Cloud credentials are missing or unauthorized, the config does not match what UltraCart granted, a query is too expensive, or a delivery credential is absent. Each message below is quoted as the CLI prints it.

Delivery errors are the one group that never stops a run. They are reported in the run summary and the report still generates.

Installation​

The install fails or resolves to the wrong registry​

@ultracart/bq-skill is published to the public npm registry. If your ~/.npmrc maps the @ultracart scope elsewhere, for example to GitHub Packages, the install fails or fetches a different package. Check with npm config get @ultracart:registry, then install from the public registry explicitly:

npm install -g @ultracart/bq-skill --registry=https://registry.npmjs.org

Chart rendering fails with a missing browser​

Chart rendering uses Puppeteer, which downloads its own copy of Chromium in a postinstall script. If npm is configured with ignore-scripts=true, that download never happens, the CLI installs fine, and then every uc-bq render or uc-bq run fails at the chart step.

Check with npm config get ignore-scripts. If it is true, install the browser directly:

npx puppeteer browsers install chrome

The CLI reports an unsupported Node version​

The package requires Node.js 24 or later. Confirm with node --version and upgrade if needed. This also applies to CI runners: set node-version: '24' in your workflow.

Authentication​

Could not load the default credentials​

Google Cloud Application Default Credentials have not been set up on this machine.

gcloud auth application-default login

For an unattended environment, set GOOGLE_APPLICATION_CREDENTIALS to the path of a service account key instead. See Authenticate with a service account.

Permission denied or Access Denied​

The account you authenticated with has not been granted BigQuery access by UltraCart. Access is provisioned per Google account and per service account, so a new service account needs registering even if your own account already works. Ask your UltraCart administrator to register it from Providing Users Access to the Data Warehouse.

If the message names an external project rather than ultracart-dw-..., this is your own project and the fix is yours: grant roles/bigquery.dataViewer on it. See External data sources.

Project not found​

The BigQuery project ID is derived from the merchant ID as ultracart-dw-{merchantid}, so a wrong merchant ID produces a project that does not exist. Check the merchant keys in .ultracart-bq.json, or re-run uc-bq init.

Dataset not found​

The dataset you are querying is not available at your taxonomy level. A standard account cannot read ultracart_dw_medium, for example. Confirm which level UltraCart assigned you, then make the taxonomy_level in your config match it. Setting a higher level in the file does not grant access; it only makes the failure less obvious. See Taxonomy levels.

Configuration​

Config file not found. Create .ultracart-bq.json in the current directory or home directory.​

The CLI looks in the working directory first and then in your home directory. Either cd into the project holding the file or create one with uc-bq init.

Config file not found at <path>. Run "uc-bq init" first.​

This variant comes from a uc-bq config subcommand, which only ever reads and writes the working directory. A config in your home directory satisfies normal commands but cannot be edited this way.

Merchant "X" not found in config. Available merchants: ...​

The -m value, or default_merchant, does not match any key under merchants. Merchant keys are matched exactly, including case, and the report directory uses the same spelling.

[WARNING] Old config format detected​

A single-merchant config with a top-level project_id was found. It is migrated in memory so the command still works, and the file on disk is unchanged. Convert it to the current format to silence the warning.

Config validation failed​

The file does not match the JSON Schema. The validator lists each problem. Unknown fields are rejected, so a typo in a key name shows up here rather than being ignored. Check a file at any time with uc-bq validate --config.

Schema file "..." not found in any schemas/ directory above ...​

The package was installed without its bundled schemas/ directory. Reinstall it.

Queries and cost​

Query would process 45.2 GB ... which exceeds the safety limit of 10.0 GB​

The dry run estimated more data than the limit allows, so nothing was executed and nothing was billed. Full message:

Query would process 45.2 GB (estimated cost: $0.2825), which exceeds the safety limit of
10.0 GB. Use --force to execute anyway, or set a higher limit with --max-bytes.

An estimate far above what the report should need usually means the query is not pruning partitions. Tightening the date range, or adding a partition_date predicate alongside the timestamp filter, generally fixes it more cheaply than raising the limit.

When the volume is genuinely expected, raise the ceiling for one command with --max-bytes, or permanently with max_query_bytes in the config. --force skips the check entirely. See Cost protection.

Charts and PDFs​

Rendering fails with a network or timeout error​

The render template loads ECharts and, for geo maps, the USA map data from a CDN at render time. A machine with no outbound network access cannot render charts. Rendering also gives up after 30 seconds.

--preview produces no file​

uc-bq render --preview is accepted by the CLI but the renderer has no preview path, so a run with --preview and no --output writes nothing. Always pass --output.

The chart is squashed in the PDF​

Wide charts read badly in portrait. Use --landscape for a single run, or set landscape: true under analysis: in the report manifest to make it permanent.

Delivery​

Every failure here is logged in the run summary and never fails the run.

SLACK_BOT_TOKEN environment variable is required for Slack delivery.​

The variable is unset in the environment running the report. The full message names the two scopes the app needs, files:write and chat:write. Setup is in Report delivery.

A Slack error naming a channel​

Messages take the form Slack getUploadURLExternal error for channel C0123456789: ... and carry the Slack API error code. Two causes account for most of them: the value in channels is a channel name rather than an ID, or the bot has not been invited to the channel. Invite it with /invite @YourBotName in the channel.

EMAIL_FROM environment variable is required for email delivery​

Every provider needs a sender address, regardless of which one you use:

export EMAIL_FROM=reports@example.com

Several providers also require the address to be verified on their side before they will accept it.

<PROVIDER>_API_KEY environment variable is required for ... email delivery.​

The key for the provider named in the manifest is missing. The variable names are listed in the Configuration reference. The Postmark variable is POSTMARK_API_KEY.

AWS SES requires @aws-sdk/client-sesv2.​

SES is the only provider with an extra dependency:

npm install @aws-sdk/client-sesv2

Unsupported email provider: "x". Supported providers: sendgrid, postmark, mailgun, resend, ses.​

The provider value in the manifest is misspelled or unsupported.

Alarms​

Percent-change alarms never fire​

They need a previous value to compare against, which lives in alarm_state.json. On a genuine first run they are skipped by design. In CI they are skipped on every run unless the state file survives between runs, because a fresh checkout starts with no history. See Keep alarm state between runs.

No data.json found. Run the report first: uc-bq run <name>​

uc-bq alarm test evaluates against results already on disk rather than running a query. Run the report once first.

An alarm never triggers despite the metric moving​

The metric value has to match a column name in data.json exactly. Confirm the column name in that file, then re-check with uc-bq alarm test.

Reports and decks​

Report and deck names containing .., /, or \ are rejected, and paths that resolve outside the report directory are blocked. Pass the directory name only, not a path.

deck create prints the report list and exits​

deck create is not interactive. Supply both --title and --reports. See Create a deck.

No report data found. Run the deck first: uc-bq deck run <name>​

uc-bq deck dashboard builds from the data.json files each report already has. Run the reports or the deck once first.

Analysis is skipped without an error​

Two conditions produce this, and both print a line explaining which: Analysis: Set --analysis-api-key or ANTHROPIC_API_KEY to generate analysis on replay. means no key was available, and Analysis: No analysis_prompt.md found. Use Claude Code to generate one. means the report has no prompt file. Neither is a failure; the chart, data, and PDF are still produced.

Was this page helpful?