{"record":{"id":"b9d1c7e2bafe7bc2","repo":"quasarframework/quasar","slug":"failed-to-reconnect-to-the-background-script","errorCode":null,"errorMessage":"Failed to reconnect to the background script.","messagePattern":"Failed to reconnect to the background script\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"app-vite/exports/bex/private/bex-bridge.js","lineNumber":108,"sourceCode":"        this.#notifyPortWaiters()\n        if (payload.removed !== void 0) {\n          this.#cleanupPort(payload.removed)\n        }\n      })\n\n      /**\n       * The background script broadcasts this one-off message on each of\n       * its (re)starts; if we were connected to a previous background\n       * instance, re-establish the connection with the new one.\n       */\n      runtime.onMessage.addListener(message => {\n        if (\n          message === reviveSignature &&\n          this.#wasConnected &&\n          !this.isConnected\n        ) {\n          this.connectToBackground().catch(err => {\n            this.warn('Failed to reconnect to the background script.', err)\n          })\n        }\n      })\n\n      return\n    }\n\n    /**\n     * Else we're the background script\n     */\n\n    this.isConnected = true\n    const onPacket = this.#onPacket.bind(this)\n\n    runtime.onConnect.addListener(port => {\n      // if it's not a bridge port on the other end,\n      // then ignore it\n      if (!portNameRE.test(port.name)) return","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/quasarframework/quasar/blob/4841521b5f635a971eb9e2710e5542efd194691b/app-vite/exports/bex/private/bex-bridge.js#L90-L126","documentation":"The Quasar BEX bridge client, on receiving a revive/ping handshake message, notices it was previously connected (#wasConnected) but is no longer connected (isConnected false), and attempts to reconnect to the background script. If that reconnect promise rejects, it logs this warning via this.warn — a diagnostic warning, not a thrown exception. It means the background script cannot be re-reached (extension context invalidated or background not responding).","triggerScenarios":"Browser-extension page content script alive while the background script restarted or was invalidated (extension reload/update, service worker terminated); a queued revive handshake triggers connectToBackground(), which rejects (port unavailable, chrome.runtime errors).","commonSituations":"Developing with `quasar dev` BEX mode and hot-reloading the extension; Chrome MV3 service worker going idle/killed; extension updated while tabs remain open; content script messaging a background that is rebuilding.","solutions":["Reload the browser tab so the content script reconnects to the fresh background context.","Check the background script's console for errors preventing it from listening for connections.","In MV3, keep the service worker responsive or implement wake-up handling in onConnect listeners.","Add application-level retry/backoff around bridge calls, or listen for the disconnect event to prompt the user to refresh."],"exampleFix":"// before\nbridge.send('some.command', data)\n// after\nif (bridge.isConnected) {\n  bridge.send('some.command', data)\n} else {\n  // queue or surface 'please reload the page' to the user\n}","handlingStrategy":"retry","validationCode":"// check bridge health before messaging\nif (!bridge.isConnected) {\n  console.warn('BEX bridge disconnected — prompt user to reload the tab')\n}","typeGuard":"function isBridgeReady(bridge: { isConnected: boolean }): boolean {\n  return bridge.isConnected === true\n}","tryCatchPattern":"try {\n  await bridge.send('some.command', payload)\n} catch (err) {\n  // background script unreachable: queue and retry or ask user to reload\n  pendingQueue.push(payload)\n  scheduleReconnect()\n}","preventionTips":["Reload open tabs after reloading/updating the extension during development.","Handle MV3 service-worker idleness: keep listeners registered at top level.","Design messages to be queueable until the bridge reconnects.","Listen for bridge disconnect events and surface a refresh prompt."],"tags":["bex","browser-extension","background-script","connection"],"backgroundTag":"bex-background-script-disconnected","analyzedSha":"4841521b5f635a971eb9e2710e5542efd194691b","analyzedAt":"2026-08-30T01:13:14.944Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}