Could not reach the Cognitum auth service. ruflo core…

Error message

Could not reach the Cognitum auth service. ruflo core functionality is unaffected — sign-in is not required for local use.

What it means

refreshAccessToken() maps an OAuthError with code 'network' from @claude-flow/security's refreshToken() into this offline diagnostic. Per ADR-308's failure policy it distinguishes "network unreachable" from "reachable but erroring": the message deliberately states that local ruflo functionality is unaffected and sign-in is not required for local use. There is no built-in retry loop; refresh is demand-driven.

Solutions

Treat it as non-fatal: continue with local ruflo commands — auth is optional for local use per ADR-308
Check basic connectivity to the auth host: curl -sS https://auth.cognitum.one or check DNS/proxy env vars (HTTPS_PROXY, HTTP_PROXY, NO_PROXY)
If behind a corporate proxy, configure it so node's fetch reaches auth.cognitum.one, then retry the command that needed auth
Retry later once network is restored; the next authenticated command will refresh on demand

Defensive patterns

Strategy: fallback

Validate before calling

// Pre-flight reachability check before demanding auth
async function authReachable(): Promise<boolean> {
  try {
    await fetch('https://auth.cognitum.one', { method: 'HEAD', signal: AbortSignal.timeout(3000) });
    return true;
  } catch { return false; }
}

Type guard

function isAuthUnreachableError(e: unknown): boolean {
  return e instanceof Error && e.message.startsWith('Could not reach the Cognitum auth service');
}

Try / catch

try {
  token = await getValidAccessToken(profile);
} catch (e) {
  if (isAuthUnreachableError(e)) {
    // ADR-308: degrade to local-only mode, never retry-loop
    return runWithoutAuth();
  }
  throw e;
}

Prevention

Design commands to work offline unless an authenticated capability is explicitly needed
Don't wrap this in an automatic retry loop — refresh is demand-driven by design
Surface the diagnostic as-is; it already explains that local use is unaffected

When it happens

Trigger: Any call to getValidAccessToken()/refreshAccessToken() while auth.cognitum.one is unreachable: no internet, DNS resolution failure, connection refused/timeout, firewall or corporate proxy blocking the host, or a TLS-intercepting middlebox dropping the connection.

Common situations: Air-gapped or hotel/offline development; CI runners behind restrictive egress allow-lists that whitelist npm but not the auth domain; VPN split-tunneling dropping the auth host; transient ISP/DNS outages during a long-lived session attempting a token refresh.

Related errors

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/caf5fa22518608de. Report an issue: GitHub.

Appendix: source

Thrown at v3/@claude-flow/cli/src/auth/client.ts:216

  };
  return { tokens, method: 'token-stdin' };
}

/**
 * Refreshes an access token. Classifies failure into network-unreachable
 * vs. a reachable-but-erroring server so callers can print an honest
 * message instead of collapsing both into "offline" (ADR-308 failure
 * policy: local ruflo functionality is never affected by auth being
 * unavailable, but the diagnostic should say WHY it's unavailable).
 */
export async function refreshAccessToken(refreshTokenValue: string): Promise<OAuthTokenResponse> {
  const sec = await loadSecurityOAuth();
  try {
    return await sec.refreshToken(refreshTokenValue);
  } catch (e) {
    if (e instanceof sec.OAuthError) {
      if (e.code === 'network') {
        throw new Error(
          'Could not reach the Cognitum auth service. ruflo core functionality is unaffected — ' +
            'sign-in is not required for local use.',
        );
      }
      throw new Error(`Cognitum auth service returned an unexpected response: ${e.message}`);
    }
    throw e;
  }
}

/**
 * Returns an access token suitable for an authenticated call.
 *
 * Fast path: a process-memory token with more than one minute remaining.
 * Slow path: load the profile's refresh token from the OS keychain, perform
 * one refresh, persist a rotated refresh token BEFORE exposing the new access
 * token, then update metadata and the process cache. Refresh is deliberately
 * demand-driven: offline-safe commands such as plain `auth status` never call

View on GitHub (pinned to fa13ee4ad6)