quasarframework/quasar · warning

Failed to reconnect to the background script.

Error message

Failed to reconnect to the background script.

What it means

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).

Source

Thrown at app-vite/exports/bex/private/bex-bridge.js:108

        this.#notifyPortWaiters()
        if (payload.removed !== void 0) {
          this.#cleanupPort(payload.removed)
        }
      })

      /**
       * The background script broadcasts this one-off message on each of
       * its (re)starts; if we were connected to a previous background
       * instance, re-establish the connection with the new one.
       */
      runtime.onMessage.addListener(message => {
        if (
          message === reviveSignature &&
          this.#wasConnected &&
          !this.isConnected
        ) {
          this.connectToBackground().catch(err => {
            this.warn('Failed to reconnect to the background script.', err)
          })
        }
      })

      return
    }

    /**
     * Else we're the background script
     */

    this.isConnected = true
    const onPacket = this.#onPacket.bind(this)

    runtime.onConnect.addListener(port => {
      // if it's not a bridge port on the other end,
      // then ignore it
      if (!portNameRE.test(port.name)) return

View on GitHub (pinned to 4841521b5f)

Solutions

1. Reload the browser tab so the content script reconnects to the fresh background context.
2. Check the background script's console for errors preventing it from listening for connections.
3. In MV3, keep the service worker responsive or implement wake-up handling in onConnect listeners.
4. Add application-level retry/backoff around bridge calls, or listen for the disconnect event to prompt the user to refresh.

Example fix

// before
bridge.send('some.command', data)
// after
if (bridge.isConnected) {
  bridge.send('some.command', data)
} else {
  // queue or surface 'please reload the page' to the user
}

// check bridge health before messaging
if (!bridge.isConnected) {
  console.warn('BEX bridge disconnected — prompt user to reload the tab')
}

function isBridgeReady(bridge: { isConnected: boolean }): boolean {
  return bridge.isConnected === true
}

try {
  await bridge.send('some.command', payload)
} catch (err) {
  // background script unreachable: queue and retry or ask user to reload
  pendingQueue.push(payload)
  scheduleReconnect()
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to inform "${portName}" about the port list.
• Failed to query the tabs to revive the content script connec
• Received an unknown message type: "${packet.type}".
• Failed to send a chunk-abort message to "${to}".
• Received a response for an unknown message id: "${message.id

AI-assisted analysis of quasarframework/quasar@4841521b5f (2026-08-30). Data as JSON: /api/errors/b9d1c7e2bafe7bc2. Report an issue: GitHub.