Troubleshooting

Start with the integrated diagnostic:

fbrcm doctor
fbrcm doctor --json

It checks credentials, connectivity, Firebase and Cloud Resource Manager API access, permissions, quota-project configuration, and local storage.

doctor expects cloudconfig.configs.get, cloudconfig.configs.update, firebase.clients.list, and firebase.clients.get on cached Firebase projects. A deliberately read-only identity can still use read commands even though the Remote Config update-permission check fails.

No projects appear

Synchronize the registry:

fbrcm projects list --update

If discovery still fails, verify that the selected identity can list projects and read Remote Config. A configured quota project also requires serviceusage.services.use for the authenticated principal.

Authentication needs attention

Inspect identities and log in again:

fbrcm auth list
fbrcm auth login example-auth-name
fbrcm auth quota-project show example-auth-name

Replace example-auth-name with the auth ID shown by fbrcm auth list.

OAuth may require a browser in human mode. JSON mode never opens one and returns structured interaction details instead. Service-account and gcloud identities validate their existing credentials without an OAuth browser flow.

If project discovery reports that a quota project is required, set an auth-level default. The two positional arguments are the local auth ID and the physical quota project ID:

fbrcm auth quota-project set example-auth-name example-quota-project-id

For a single cached Firebase project, inspect or override the selection with:

fbrcm project quota-project show example-project-id
fbrcm project quota-project set example-project-id example-quota-project-id
fbrcm project quota-project unset example-project-id

ADC quota_project_id is considered only for gcloud identities. fbrcm doctor verifies both resolution and serviceusage.services.use access.

Reads look stale

Force a live cache revalidation:

fbrcm get --project '=example-project-id' --update

Check whether a local draft is active, because normal effective reads include draft state. Use draft diff to inspect it, or draft discard only when that local intent is no longer needed.

Offline mode appeared unexpectedly

The TUI enters offline mode after its startup connectivity probe fails. The CLI enters offline mode whenever FBRCM_OFFLINE is defined, even as an empty value or 0.

Check proxy variables and unset the override when live access is intended:

unset FBRCM_OFFLINE

A write reports a conflict

Another client changed Firebase after fbrcm loaded the template, or a draft rebase found overlapping local and remote edits. Refresh current state and review again. Do not blindly retry a complete-template publication.

Draft conflicts preserve the draft. Use:

fbrcm draft diff example-project-id --against current

An editor does not return

GUI editors must wait for the staged file to close:

FBRCM_EDITOR="code --wait" fbrcm

For CLI configuration editing, the same setting applies to fbrcm config edit.

The TUI is too small

The minimum supported terminal size is 80 columns by 20 rows. Enlarge the window or reduce terminal font size. Human CLI tables adapt to narrow widths independently.

JSON automation did not perform an action

Inspect outcome, exit_code, and the structured problems. Status 10 means the operation requires explicit interaction such as --yes, an import merge choice, OAuth authorization, or overwrite approval. Follow the published remediation strategy only after checking authorization and target scope.