Budibase/budibase · error

Connection refused when using proxy. Check proxy configurati

Error message

Connection refused when using proxy. Check proxy configuration and ensure the proxy server is accessible. Original error: ${error.message}

What it means

The REST integration's fetch call failed with an ECONNREFUSED cause while a proxy dispatcher was in use. The integration wraps the underlying undici error to indicate the refusal happened through the configured proxy, distinguishing it from a direct connection failure. It is thrown so the user knows to inspect proxy settings rather than the target URL.

Source

Thrown at packages/server/src/integrations/rest.ts:1010

        cause: error.cause?.message,
        code: error.cause?.code,
        hasDispatcher,
        usedProxyDispatcher,
        isHttpsUrl: url.startsWith("https://"),
        rejectUnauthorized,
      })
      if (
        error.cause?.code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE" ||
        error.cause?.code === "CERT_UNTRUSTED" ||
        error.cause?.code === "SELF_SIGNED_CERT_IN_CHAIN"
      ) {
        throw new Error(
          `SSL certificate verification failed for ${url}. Consider setting rejectUnauthorized to false if using self-signed certificates. Original error: ${error.message}`
        )
      }

      if (error.cause?.code === "ECONNREFUSED" && usedProxyDispatcher) {
        throw new Error(
          `Connection refused when using proxy. Check proxy configuration and ensure the proxy server is accessible. Original error: ${error.message}`
        )
      }
      throw error
    }
    if (response.status === 401 && retry401) {
      const { authConfigId, authConfigType } = query
      if (authConfigType === RestAuthType.OAUTH2 && authConfigId) {
        await sdk.oauth2.cleanStoredTokensForAuthConfig(authConfigId)
        return await this._req(query, { ...opts, retry401: false })
      }
    }
    const parsed = await this.parseResponse(response, pagination)
    if (includeRequest) {
      const request = this.buildRequestPreview(built, opts)
      if (request) {
        parsed.extra = {
          raw: undefined,

View on GitHub (pinned to a81a902e9a)

Solutions

1. Verify the proxy server is running and reachable: curl -x http://<proxy-host>:<proxy-port> https://example.com from the server host.
2. Check the proxy configuration (environment variables like HTTP_PROXY/HTTPS_PROXY or the integration's proxy settings) for typos in host/port and correct them.
3. If no proxy is needed, remove the proxy configuration so requests go direct.
4. Confirm firewall/security-group rules allow the Budibase server to reach the proxy port.
5. Check proxy service logs and restart it if it crashed.

Example fix

// before (env pointing at dead proxy)
HTTPS_PROXY=http://127.0.0.1:8888 yarn dev
// after (corrected running proxy, or removed)
HTTPS_PROXY=http://127.0.0.1:9090 yarn dev  # or unset HTTPS_PROXY

const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY
if (proxyUrl) {
  const { hostname, port } = new URL(proxyUrl)
  const net = await import("node:net")
  await new Promise((res, rej) => {
    const s = net.connect(Number(port), hostname, () => { s.destroy(); res(null) })
    s.on("error", rej)
  })
}

function isProxyRefused(err: unknown): err is Error & { cause?: { code?: string } } {
  return err instanceof Error &&
    err.message.includes("Connection refused when using proxy") &&
    (err.cause as { code?: string } | undefined)?.code === "ECONNREFUSED"
}

try {
  await restIntegration.read(query)
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Connection refused when using proxy")) {
    // fall back to direct connection or alert on proxy health
  } else { throw err }
}

When it happens

Trigger: Executing a REST query (RestIntegration) with a proxy configured (usedProxyDispatcher set) where the proxy host is down, the port is wrong, or the proxy refuses the connection (error.cause?.code === 'ECONNREFUSED').

Common situations: PROXY env var or integration proxy config pointing at a stopped local proxy (e.g. mitm/charles not running); corporate proxy decommissioned or IP changed; typo in proxy port; container networking where the proxy hostname is unreachable from the server process; proxy crashed under load.

Understand the failure class

• Connection failures: ECONNREFUSED, ECONNRESET, and friends — why connections get refused, reset, or dropped.

Related errors

• Failed to connect to resolved IP for ${hostname}: unknown ne
• Redis error: ${err}
• Error getting account by tenantId ${tenantId}
• ${err.message}
• Unexpected response when fetching openid-configuration: ${re

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/b4d82cd1adacfb49. Report an issue: GitHub.