@@ -0,0 +1,12 @@
+---
+'@objectstack/objectql': patch
+---
+
+fix(objectql): the 503 `ERR_DATASOURCE_UNAVAILABLE` text for a failed datasource no longer blames a startup connect under `OS_ALLOW_DRIVER_CONNECT_FAILURE`
+
+Clause-②: no
+Metadata-protocol: none
+
+A datasource whose connect failed answers a read of its bound objects with `503 ERR_DATASOURCE_UNAVAILABLE`. Its message used to say the datasource "failed to connect at startup and the server was started with `OS_ALLOW_DRIVER_CONNECT_FAILURE`" and that the server "must be restarted". That was false for a datasource declared by a package installed into a running server (`POST /api/v1/marketplace/install-local`) and for one created in Setup: no flag was involved, and saving it again or reinstalling the package re-runs the connect.
+
+The connection layer records every failed connect the same way, so the message now names no origin: "its last connect attempt failed, so no driver serves it", ending "See Setup → Datasources or the server log for the cause." Only while `OS_ALLOW_DRIVER_CONNECT_FAILURE` is set does it add that a datasource declared in code whose connect failed at startup is re-connected only by a restart. The code, the 503 status and the `reason: failed` class are unchanged, and the message still never carries the underlying cause.
@@ -400,9 +400,10 @@ no stored version can ever equal "nothing".
 ### Datasource Unavailable — `503 Service Unavailable`
 
 Returned when the object's declared `datasource` has no live driver: the host's
-connect policy refused it, or it failed to connect at startup and the server was
-started with `OS_ALLOW_DRIVER_CONNECT_FAILURE`. Nothing about the request is
-wrong, and the state may clear — so this is a `503`, not a `400` or a `500`.
+connect policy refused it, or its last connect attempt failed — at startup under
+`OS_ALLOW_DRIVER_CONNECT_FAILURE`, when a package declaring it was installed, or
+when it was created in Setup. Nothing about the request is wrong, and the state
+may clear — so this is a `503`, not a `400` or a `500`.
 
 `reason` is the class (`blocked` | `failed`). The underlying cause is
 deliberately **not** included — it routinely contains hosts, ports and DSNs; it
 
@@ -227,8 +227,11 @@ pull an otherwise-working replica out of the load balancer.
 An object bound to a datasource with no live driver fails with
 `ERR_DATASOURCE_UNAVAILABLE` (HTTP **503**), and the message says which situation
 it is ([#3828](https://github.com/objectstack-ai/objectstack/issues/3828)):
-refused by policy, or a connect that failed under
-`OS_ALLOW_DRIVER_CONNECT_FAILURE`. A datasource name that was never declared
+refused by policy, or a connect that failed. A failed connect is recorded the
+same way whether it failed at startup under `OS_ALLOW_DRIVER_CONNECT_FAILURE`,
+at a package install or in Setup, so the message names no origin; it says a
+restart re-runs the connect only while that flag is set, and then only for a
+datasource declared in code. A datasource name that was never declared
 still gets the original `is not registered` — that one really is an authoring
 bug, and there is nothing to add.
 
 
@@ -7,7 +7,7 @@
 // typo that isn't there. The connection layer knows which one it is; the engine
 // just had no way to be told.
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { ObjectQL } from './engine.js';
 import { DatasourceUnavailableError } from './driver-connect-errors.js';
 
@@ -67,16 +67,48 @@ describe('ObjectQL.getDriver — a declared datasource with no driver (framework
     expect((await queryError(engine)).message).toContain('require the Scale plan');
   });
 
-  it('says the connect failed and a restart is needed, for the degraded-boot case', async () => {
-    const engine = engineWithBoundObject();
-    engine.markDatasourceUnavailable({ name: 'analytics', kind: 'failed' });
+  // A `failed` record is the same `{ kind: 'failed' }` for a boot connect the
+  // flag waved through, a package installed into the running server and a
+  // Setup-created datasource: the connection layer records no origin. The
+  // flag is the one fact that separates them — without it the first cannot
+  // exist, because that boot is refused.
+  describe('a failed connect', () => {
+    afterEach(() => {
+      vi.unstubAllEnvs();
+    });
 
-    const err = await queryError(engine);
-    expect(err.kind).toBe('failed');
-    expect(err.message).toContain('OS_ALLOW_DRIVER_CONNECT_FAILURE');
-    // The durable fact: the client may reconnect, but nothing re-runs the
-    // connect, so waiting it out does not help (#3759).
-    expect(err.message).toContain('restarted');
+    it('says the connect failed, and a restart only conditionally, while OS_ALLOW_DRIVER_CONNECT_FAILURE is set', async () => {
+      // The boot-under-flag origin: the client may reconnect, but nothing
+      // re-runs the connect, so waiting it out does not help (#3759).
+      vi.stubEnv('OS_ALLOW_DRIVER_CONNECT_FAILURE', '1');
+      const engine = engineWithBoundObject();
+      engine.markDatasourceUnavailable({ name: 'analytics', kind: 'failed' });
+
+      const err = await queryError(engine);
+      expect(err.kind).toBe('failed');
+      expect(err.message).toContain('its last connect attempt failed');
+      expect(err.message).toContain('OS_ALLOW_DRIVER_CONNECT_FAILURE is set on this server');
+      expect(err.message).toContain('if this datasource is declared in code');
+      expect(err.message).toContain('until the server is restarted');
+    });
+
+    it('names neither the flag nor a restart without it — the install-local and Setup origins', async () => {
+      // A datasource whose connect failed when its package was installed into
+      // the running server, or when it was created in Setup: no flag was
+      // involved, and a restart is not what re-runs its connect.
+      vi.stubEnv('OS_ALLOW_DRIVER_CONNECT_FAILURE', '');
+      const engine = engineWithBoundObject();
+      engine.markDatasourceUnavailable({ name: 'analytics', kind: 'failed' });
+
+      const err = await queryError(engine);
+      expect(err.kind).toBe('failed');
+      expect(err.code).toBe('ERR_DATASOURCE_UNAVAILABLE');
+      expect(err.message).toContain('its last connect attempt failed, so no driver serves it.');
+      expect(err.message).not.toContain('OS_ALLOW_DRIVER_CONNECT_FAILURE');
+      expect(err.message).not.toMatch(/restart/i);
+      expect(err.message).not.toContain('at startup');
+      expect(err.message).toContain('See Setup → Datasources or the server log for the cause.');
+    });
   });
 
   it('never carries the underlying cause — that is what leaks hosts and DSNs', async () => {
@@ -86,7 +118,7 @@ describe('ObjectQL.getDriver — a declared datasource with no driver (framework
     engine.markDatasourceUnavailable({ name: 'analytics', kind: 'failed' });
     const err = await queryError(engine);
     expect(err.message).not.toMatch(/ECONNREFUSED|\d+\.\d+\.\d+\.\d+|postgres:\/\//);
-    expect(err.message).toContain('startup logs');
+    expect(err.message).toContain('Setup → Datasources');
   });
 
   it('clears the explanation once the datasource connects', async () => {
 
@@ -1,5 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
+import { resolveAllowDriverConnectFailure } from '@objectstack/types';
+
 /** One boot-registered driver whose `connect()` rejected during engine init. */
 export interface DriverConnectFailure {
   driverName: string;
@@ -231,8 +233,10 @@ export const DATASOURCE_UNAVAILABLE_CODE = 'ERR_DATASOURCE_UNAVAILABLE' as const
  * is not registered.`:
  *
  *  1. the host's connect policy refused it (plan / egress isolation),
- *  2. it failed to connect at boot and `OS_ALLOW_DRIVER_CONNECT_FAILURE` let
- *     the server start anyway,
+ *  2. its connect failed — at boot under `OS_ALLOW_DRIVER_CONNECT_FAILURE`, when
+ *     a package declaring it was installed into the running server, or when it
+ *     was created in Setup (the record does not say which; see
+ *     `degradedBootNote`),
  *  3. the app misspelled the datasource name, and
  *  4. it is declared `active: false`.
  *
@@ -266,16 +270,46 @@ export class DatasourceUnavailableError extends Error {
           `error. It may clear; retry later.`
         : kind === 'blocked'
         ? `: the host's datasource connect policy refused it.`
-        : `: it failed to connect at startup and the server was started with ` +
-          `OS_ALLOW_DRIVER_CONNECT_FAILURE. Nothing re-runs the connect — the server must be ` +
-          `restarted once the datasource is reachable.`;
+        : `: its last connect attempt failed, so no driver serves it.` + degradedBootNote();
     const detail = publicDetail ? ` ${publicDetail}` : '';
-    const where = kind === 'remote' ? 'the server log' : 'the startup logs or Setup → Datasources';
+    const where =
+      kind === 'remote'
+        ? 'the server log'
+        : kind === 'blocked'
+        ? 'the startup logs or Setup → Datasources'
+        : 'Setup → Datasources or the server log';
     super(`${head}${why}${detail} See ${where} for the cause.`);
     this.name = 'DatasourceUnavailableError';
   }
 }
 
+/**
+ * The `failed` arm's restart sentence, or nothing.
+ *
+ * A `failed` record is the same `{ kind: 'failed' }` whatever produced it: a
+ * code datasource whose boot connect failed under
+ * `OS_ALLOW_DRIVER_CONNECT_FAILURE`, one declared by a package installed into
+ * the running server, and one created in Setup. A restart re-runs each of
+ * them, but only the first has no other door — saving re-runs a Setup
+ * datasource's connect, reinstalling re-runs a package's — and only the first
+ * can exist only while the flag is set, because without it that boot is
+ * refused. So the flag is the one fact that can make the sentence true, and it
+ * is said conditionally: with the flag set, the record may still come from
+ * either of the other two.
+ *
+ * The flag is read through `resolveAllowDriverConnectFailure`, the one parse
+ * the boot paths use, which answers `false` where there is no `process`, so
+ * this never throws inside the constructor.
+ */
+function degradedBootNote(): string {
+  if (!resolveAllowDriverConnectFailure()) return '';
+  return (
+    ` OS_ALLOW_DRIVER_CONNECT_FAILURE is set on this server: if this datasource is declared in code ` +
+    `and its connect failed at startup, the flag let the server start without it, and nothing re-runs ` +
+    `that connect until the server is restarted.`
+  );
+}
+
 /**
  * The degraded-boot banner now lives in `@objectstack/types` because
  * `DatasourceConnectionService` owes the operator the same banner for the same
 
@@ -280,7 +280,7 @@ function makeStore(rows: Record<string, Row[]>, detail: DetailVariant = 'valid',
 function datasourceOutage(object: string): Error {
   const e = new Error(
     `[ObjectQL] Datasource 'primary' configured for object '${object}' is declared but not connected: ` +
-      `it failed to connect at startup and the server was started with OS_ALLOW_DRIVER_CONNECT_FAILURE.`,
+      `its last connect attempt failed, so no driver serves it. See Setup → Datasources or the server log for the cause.`,
   ) as Error & { code: string; datasource: string };
   e.name = 'DatasourceUnavailableError';
   e.code = 'ERR_DATASOURCE_UNAVAILABLE';
 
@@ -60,7 +60,7 @@ type Row = Record<string, unknown>;
 function datasourceOutage(object: string): Error {
   const e = new Error(
     `[ObjectQL] Datasource 'primary' configured for object '${object}' is declared but not connected: ` +
-      `it failed to connect at startup and the server was started with OS_ALLOW_DRIVER_CONNECT_FAILURE.`,
+      `its last connect attempt failed, so no driver serves it. See Setup → Datasources or the server log for the cause.`,
   ) as Error & { code: string; datasource: string };
   e.name = 'DatasourceUnavailableError';
   e.code = 'ERR_DATASOURCE_UNAVAILABLE';