Quick Diagnostic Checklist

1. Verify connection status — Open BrightTally → Settings. If the badge says Not Connected, reconnect before investigating further.
2. Check recent logs — The plugin writes OAuth errors to wp-content/debug.log when WP_DEBUG_LOG is enabled.
3. Confirm time sync — OAuth tokens can fail if your server clock drifts more than 5 minutes. Ensure NTP is running.

Common OAuth Errors

invalid_grant

Occurs when the authorization code expires or has already been used.

Fix

• Restart the connection flow from BrightTally → Settings → Sign In to BrightTally.
• Make sure the popup is not closed prematurely by pop-up blockers.

redirect_uri_mismatch

BrightTally could not validate the callback URL supplied by WordPress.

Fix

• Ensure the callback matches https://your-site.com/wp-admin/admin.php?page=bright-tally-settings&oauth_callback=1.
• If you are on staging, update the Documentation Base URL and API URL to match the staging host before retrying.

requires_login

The BrightTally session expired inside the popup.

Fix

• Log in inside the popup window when prompted.
• If the popup keeps redirecting to the dashboard, clear cookies for brighttally.com and try again.

Sync Issues After Connecting

• Polls not refreshing: Click Refresh on the Polls screen. If that fails, disconnect and reconnect so the plugin can fetch new tokens.
• Response counts frozen: There may be active caching on the WordPress side. Clear full-page caches and CDN layers, then reload.
• Preview differs from production: Confirm both sites point to the same BrightTally account (Settings → API URL).

When to Contact Support

Gather the following details before reaching out:

• WordPress site URL & environment (production, staging, local)
• PHP version and hosting provider
• Excerpts from debug.log around the time of failure
• Workspace slug in BrightTally

Email the information to support@brighttally.com with WordPress OAuth in the subject line. Enterprise customers can also open a ticket via the BrightTally admin console for priority handling.