Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix Linux startup with limited shared memory (PRD-8494) (#4435)

mike-inkeep99d758762821
diff --git a/.changeset/linux-dev-shm-posture.md b/.changeset/linux-dev-shm-posture.md
new file mode 100644
index 000000000..9d738e815
--- /dev/null
+++ b/.changeset/linux-dev-shm-posture.md
@@ -0,0 +1,10 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-desktop": patch
+---
+
+Linux desktop: avoid blank startup windows caused by a small `/dev/shm` when the temporary filesystem has enough free space. This affects Linux environments with constrained shared-memory mounts, including some containers and minimal VMs.
+
+When `/dev/shm` has less than 512 MiB available, OpenKnowledge moves Chromium's shared memory to its temporary directory only if that destination has at least 512 MiB free. The temporary directory follows Chromium's Linux rules: `TMPDIR`, or `/tmp` when unset or empty. Hosts with sufficient shared memory keep using `/dev/shm`.
+
+If both filesystems are too small, startup can still remain blank: free space on the temporary filesystem or configure the `/dev/shm` tmpfs mount with `size=1G`. For Docker containers, use `--shm-size=1g` when starting the container. The desktop log now records the selected location, available space, thresholds, measurement errors, and show-gate warnings so diagnostic bundles include the startup evidence.
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 43a420ec8..ecee2f9be 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -7,6 +7,7 @@ import {
mkdirSync,
readFileSync,
realpathSync,
+ statfsSync,
statSync,
writeFileSync,
} from 'node:fs';
@@ -317,6 +318,7 @@ import {
detectGraphicalAuthCommand,
runManualInstallFallbackDialog,
} from './linux-install-fallback.ts';
+import { applyDevShmPosture } from './linux-shm-posture.ts';
import { resolveLocalOpCliInvocation } from './local-op-cli-invocation.ts';
import { createMenuTranslator, resolveMenuCatalogDir } from './main-i18n.ts';
import { createMainThreadWatchdog } from './main-thread-watchdog.ts';
@@ -1067,9 +1069,7 @@ function yieldRestoreToDeepLink(): void {
const showGate: ShowGateRegistry = createShowGateRegistry({
log: {
- warn: (obj, msg) => {
- console.warn(JSON.stringify({ ...obj, msg }));
- },
+ warn: (obj, msg) => getLogger('show-gate').warn({ ...obj }, msg),
},
setTimeout: (cb, ms) => setTimeout(cb, ms),
clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
@@ -5611,6 +5611,15 @@ installStdioBrokenPipeGuard(process, {
app.commandLine.appendSwitch('use-system-ca');
trustSystemCertificates();
+applyDevShmPosture({
+ platform: process.platform,
+ statfs: (path) => statfsSync(path),
+ env: process.env,
+ appendSwitch: (name) => app.commandLine.appendSwitch(name),
+ log: (level, facts) =>
+ getRootDesktopLogger()[level](facts, 'linux shared-memory posture for chromium'),
+});
+
if (!app.isPackaged) {
const resolved = resolveEffectiveInstanceName(process.env, app.getAppPath(), {
autoDeriveEnabled: process.env.OK_DESKTOP_E2E_SMOKE !== '1',
diff --git a/packages/desktop/src/main/linux-shm-posture.ts b/packages/desktop/src/main/linux-shm-posture.ts
new file mode 100644
index 000000000..49a35393a
--- /dev/null
+++ b/packages/desktop/src/main/linux-shm-posture.ts
@@ -0,0 +1,123 @@
+export const DEV_SHM_PATH = '/dev/shm';
+export const MIN_AVAILABLE_SHARED_MEMORY_BYTES = 512 * 1024 * 1024;
+export const DISABLE_DEV_SHM_USAGE_SWITCH = 'disable-dev-shm-usage';
+
+type DevShmDecision =
+ | 'not-linux'
+ | 'dev-shm-sufficient'
+ | 'redirect-to-tmpdir'
+ | 'keep-dev-shm-tmpdir-unreadable'
+ | 'keep-dev-shm-tmpdir-too-small';
+
+const DEV_SHM_LOG_LEVELS = {
+ 'not-linux': null,
+ 'dev-shm-sufficient': 'info',
+ 'redirect-to-tmpdir': 'info',
+ 'keep-dev-shm-tmpdir-unreadable': 'warn',
+ 'keep-dev-shm-tmpdir-too-small': 'warn',
+} satisfies Record<DevShmDecision, 'info' | 'warn' | null>;
+
+export interface FsSpace {
+ bavail: number;
+ bsize: number;
+ blocks: number;
+}
+
+export interface DevShmPostureDeps {
+ platform: NodeJS.Platform;
+ statfs: (path: string) => FsSpace;
+ tmpDir: string;
+}
+
+export interface DevShmPosture {
+ decision: DevShmDecision;
+ event: 'desktop.linux-dev-shm-posture';
+ thresholdBytes: number;
+ devShmAvailableBytes: number | null;
+ devShmTotalBytes: number | null;
+ tmpDir: string;
+ tmpDirAvailableBytes: number | null;
+ tmpDirMinAvailableBytes: number;
+ devShmErrorCode: string | null;
+ tmpDirErrorCode: string | null;
+}
+
+type MeasuredSpace =
+ | { available: number; total: number; errorCode: null }
+ | { available: null; total: null; errorCode: string };
+
+function measure(statfs: DevShmPostureDeps['statfs'], path: string): MeasuredSpace {
+ try {
+ const space = statfs(path);
+ return {
+ available: space.bavail * space.bsize,
+ total: space.blocks * space.bsize,
+ errorCode: null,
+ };
+ } catch (error) {
+ const errorCode =
+ error !== null &&
+ typeof error === 'object' &&
+ 'code' in error &&
+ typeof error.code === 'string'
+ ? error.code
+ : 'UNKNOWN';
+ return { available: null, total: null, errorCode };
+ }
+}
+
+export function decideDevShmPosture(deps: DevShmPostureDeps): DevShmPosture {
+ const posture: DevShmPosture = {
+ decision: 'not-linux',
+ event: 'desktop.linux-dev-shm-posture',
+ thresholdBytes: MIN_AVAILABLE_SHARED_MEMORY_BYTES,
+ devShmAvailableBytes: null,
+ devShmTotalBytes: null,
+ tmpDir: deps.tmpDir,
+ tmpDirAvailableBytes: null,
+ tmpDirMinAvailableBytes: MIN_AVAILABLE_SHARED_MEMORY_BYTES,
+ devShmErrorCode: null,
+ tmpDirErrorCode: null,
+ };
+ if (deps.platform !== 'linux') return posture;
+
+ const devShm = measure(deps.statfs, DEV_SHM_PATH);
+ posture.devShmAvailableBytes = devShm.available;
+ posture.devShmTotalBytes = devShm.total;
+ posture.devShmErrorCode = devShm.errorCode;
+ if (devShm.available !== null && devShm.available >= MIN_AVAILABLE_SHARED_MEMORY_BYTES) {
+ posture.decision = 'dev-shm-sufficient';
+ return posture;
+ }
+
+ const tmp = measure(deps.statfs, deps.tmpDir);
+ posture.tmpDirAvailableBytes = tmp.available;
+ posture.tmpDirErrorCode = tmp.errorCode;
+ if (tmp.available === null) {
+ posture.decision = 'keep-dev-shm-tmpdir-unreadable';
+ return posture;
+ }
+ if (tmp.available < MIN_AVAILABLE_SHARED_MEMORY_BYTES) {
+ posture.decision = 'keep-dev-shm-tmpdir-too-small';
+ return posture;
+ }
+ posture.decision = 'redirect-to-tmpdir';
+ return posture;
+}
+
+export function applyDevShmPosture(
+ deps: Omit<DevShmPostureDeps, 'tmpDir'> & {
+ env: NodeJS.ProcessEnv;
+ appendSwitch: (name: string) => void;
+ log: (level: 'info' | 'warn', facts: DevShmPosture) => void;
+ },
+): DevShmPosture {
+ const posture = decideDevShmPosture({ ...deps, tmpDir: deps.env.TMPDIR || '/tmp' });
+ if (posture.decision === 'not-linux') return posture;
+ if (posture.decision === 'redirect-to-tmpdir') {
+ deps.appendSwitch(DISABLE_DEV_SHM_USAGE_SWITCH);
+ }
+ const level = DEV_SHM_LOG_LEVELS[posture.decision];
+ deps.log(level, posture);
+ return posture;
+}
diff --git a/packages/desktop/tests/main/linux-shm-posture.test.ts b/packages/desktop/tests/main/linux-shm-posture.test.ts
new file mode 100644
index 000000000..2ea0f56a9
--- /dev/null
+++ b/packages/desktop/tests/main/linux-shm-posture.test.ts
@@ -0,0 +1,296 @@
+import { describe, expect, test } from 'vitest';
+import {
+ applyDevShmPosture,
+ DEV_SHM_PATH,
+ type DevShmPosture,
+ DISABLE_DEV_SHM_USAGE_SWITCH,
+ decideDevShmPosture,
+ type FsSpace,
+ MIN_AVAILABLE_SHARED_MEMORY_BYTES,
+} from '../../src/main/linux-shm-posture.ts';
+
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+const BSIZE = 4096;
+const TMP = '/tmp';
+
+function space(availableBytes: number, totalBytes = availableBytes): FsSpace {
+ return { bsize: BSIZE, bavail: availableBytes / BSIZE, blocks: totalBytes / BSIZE };
+}
+
+function statfsFrom(table: Record<string, FsSpace | Error>) {
+ const calls: string[] = [];
+ const statfs = (path: string): FsSpace => {
+ calls.push(path);
+ const entry = table[path];
+ if (entry === undefined) throw new Error(`ENOENT: ${path}`);
+ if (entry instanceof Error) throw entry;
+ return entry;
+ };
+ return { statfs, calls };
+}
+
+describe('decideDevShmPosture', () => {
+ test('non-linux platforms never apply the switch and never touch the filesystem', () => {
+ const { statfs, calls } = statfsFrom({});
+ for (const platform of ['darwin', 'win32'] as const) {
+ const posture = decideDevShmPosture({ platform, statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('not-linux');
+ }
+ expect(calls).toEqual([]);
+ });
+
+ test('a roomy /dev/shm keeps chromium on /dev/shm and never reads the tmpdir', () => {
+ const { statfs, calls } = statfsFrom({
+ [DEV_SHM_PATH]: space(2 * GiB),
+ [TMP]: space(100 * GiB),
+ });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('dev-shm-sufficient');
+ expect(posture.devShmAvailableBytes).toBe(2 * GiB);
+ expect(posture.tmpDirAvailableBytes).toBeNull();
+ expect(calls).toEqual([DEV_SHM_PATH]);
+ });
+
+ test('exactly the threshold counts as sufficient', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(MIN_AVAILABLE_SHARED_MEMORY_BYTES) });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('dev-shm-sufficient');
+ expect(posture.thresholdBytes).toBe(512 * MiB);
+ });
+
+ test('a 64 MiB /dev/shm with a roomier tmpdir redirects chromium to the tmpdir', () => {
+ const { statfs } = statfsFrom({
+ [DEV_SHM_PATH]: space(64 * MiB),
+ [TMP]: space(20 * GiB, 40 * GiB),
+ });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('redirect-to-tmpdir');
+ expect(posture).toMatchObject({
+ devShmAvailableBytes: 64 * MiB,
+ devShmTotalBytes: 64 * MiB,
+ tmpDir: TMP,
+ tmpDirAvailableBytes: 20 * GiB,
+ });
+ });
+
+ test('available space decides, not mount size: a large but nearly full /dev/shm redirects', () => {
+ const { statfs } = statfsFrom({
+ [DEV_SHM_PATH]: space(100 * MiB, 8 * GiB),
+ [TMP]: space(20 * GiB),
+ });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('redirect-to-tmpdir');
+ expect(posture.devShmTotalBytes).toBe(8 * GiB);
+ });
+
+ test('two 64 MiB filesystems retain /dev/shm with a capacity warning', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(64 * MiB), [TMP]: space(64 * MiB) });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('keep-dev-shm-tmpdir-too-small');
+ });
+
+ test('a missing /dev/shm redirects when the tmpdir is readable', () => {
+ const { statfs } = statfsFrom({ [TMP]: space(20 * GiB) });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('redirect-to-tmpdir');
+ expect(posture.devShmAvailableBytes).toBeNull();
+ expect(posture.devShmTotalBytes).toBeNull();
+ });
+
+ test('an unreadable tmpdir keeps chromium on /dev/shm', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(64 * MiB), [TMP]: new Error('EACCES') });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('keep-dev-shm-tmpdir-unreadable');
+ expect(posture.tmpDirAvailableBytes).toBeNull();
+ });
+});
+
+describe('fallback capacity and diagnostics', () => {
+ test.each([0, 32, 65, 165, 511])(
+ 'a %i MiB target is not viable even with a smaller /dev/shm',
+ (mib) => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(0), [TMP]: space(mib * MiB) });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('keep-dev-shm-tmpdir-too-small');
+ expect(posture.tmpDirMinAvailableBytes).toBe(MIN_AVAILABLE_SHARED_MEMORY_BYTES);
+ expect(posture.tmpDirAvailableBytes).toBe(mib * MiB);
+ },
+ );
+
+ test('exactly 512 MiB at the fallback destination permits redirecting a 64 MiB /dev/shm', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(64 * MiB), [TMP]: space(512 * MiB) });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture.decision).toBe('redirect-to-tmpdir');
+ expect(posture.tmpDirMinAvailableBytes).toBe(512 * MiB);
+ });
+
+ test.each(['ENOENT', 'EACCES', 'ENOSYS'])(
+ 'preserves the /dev/shm %s error in the diagnostic',
+ (code) => {
+ const { statfs } = statfsFrom({
+ [DEV_SHM_PATH]: Object.assign(new Error('statfs failed'), { code }),
+ [TMP]: space(GiB),
+ });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture).toMatchObject({
+ decision: 'redirect-to-tmpdir',
+ devShmAvailableBytes: null,
+ devShmErrorCode: code,
+ tmpDirErrorCode: null,
+ });
+ },
+ );
+
+ test('preserves the temp directory measurement error', () => {
+ const { statfs } = statfsFrom({
+ [DEV_SHM_PATH]: space(64 * MiB),
+ [TMP]: Object.assign(new Error('statfs failed'), { code: 'EACCES' }),
+ });
+ const posture = decideDevShmPosture({ platform: 'linux', statfs, tmpDir: TMP });
+ expect(posture).toMatchObject({
+ decision: 'keep-dev-shm-tmpdir-unreadable',
+ devShmErrorCode: null,
+ tmpDirErrorCode: 'EACCES',
+ });
+ });
+
+ test('an unclassified thrown value does not crash startup', () => {
+ const posture = decideDevShmPosture({
+ platform: 'linux',
+ statfs: () => {
+ throw null;
+ },
+ tmpDir: TMP,
+ });
+ expect(posture).toMatchObject({
+ decision: 'keep-dev-shm-tmpdir-unreadable',
+ devShmErrorCode: 'UNKNOWN',
+ tmpDirErrorCode: 'UNKNOWN',
+ });
+ });
+});
+
+describe('applyDevShmPosture', () => {
+ function effects() {
+ const switches: string[] = [];
+ const logs: Array<{ level: 'info' | 'warn'; facts: DevShmPosture }> = [];
+ return {
+ switches,
+ logs,
+ appendSwitch: (name: string) => {
+ switches.push(name);
+ },
+ log: (level: 'info' | 'warn', facts: DevShmPosture) => {
+ logs.push({ level, facts });
+ },
+ };
+ }
+
+ test('applies the Chromium switch before logging its diagnostic', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(64 * MiB), [TMP]: space(750 * MiB) });
+ const recorded = effects();
+ const posture = applyDevShmPosture({
+ platform: 'linux',
+ statfs,
+ env: {},
+ appendSwitch: recorded.appendSwitch,
+ log: (level, facts) => {
+ expect(recorded.switches).toEqual([DISABLE_DEV_SHM_USAGE_SWITCH]);
+ recorded.log(level, facts);
+ },
+ });
+ expect(recorded.logs).toEqual([
+ {
+ level: 'info',
+ facts: {
+ event: 'desktop.linux-dev-shm-posture',
+ decision: 'redirect-to-tmpdir',
+ thresholdBytes: 512 * MiB,
+ devShmAvailableBytes: 64 * MiB,
+ devShmTotalBytes: 64 * MiB,
+ tmpDir: TMP,
+ tmpDirAvailableBytes: 750 * MiB,
+ tmpDirMinAvailableBytes: 512 * MiB,
+ devShmErrorCode: null,
+ tmpDirErrorCode: null,
+ },
+ },
+ ]);
+ expect(posture.decision).toBe('redirect-to-tmpdir');
+ });
+
+ test.each(['darwin', 'win32'] as const)(
+ '%s performs no measurement, switch change, or logging',
+ (platform) => {
+ const { statfs, calls } = statfsFrom({});
+ const recorded = effects();
+ applyDevShmPosture({ platform, statfs, env: {}, ...recorded });
+ expect(calls).toEqual([]);
+ expect(recorded.switches).toEqual([]);
+ expect(recorded.logs).toEqual([]);
+ },
+ );
+
+ test('sufficient shared memory is logged at info without adding a switch', () => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(512 * MiB) });
+ const recorded = effects();
+ const posture = applyDevShmPosture({ platform: 'linux', statfs, env: {}, ...recorded });
+ expect(recorded.switches).toEqual([]);
+ expect(recorded.logs).toEqual([{ level: 'info', facts: posture }]);
+ });
+
+ test.each([undefined, ''])('ignores TMP and TEMP when TMPDIR is %s', (tmpdir) => {
+ const { statfs, calls } = statfsFrom({
+ [DEV_SHM_PATH]: space(64 * MiB),
+ [TMP]: space(165 * MiB),
+ '/other-mount': space(20 * GiB),
+ });
+ const recorded = effects();
+ const posture = applyDevShmPosture({
+ platform: 'linux',
+ statfs,
+ env: { TMPDIR: tmpdir, TMP: '/other-mount', TEMP: '/other-mount' },
+ ...recorded,
+ });
+ expect(calls).toEqual([DEV_SHM_PATH, TMP]);
+ expect(recorded.switches).toEqual([]);
+ expect(posture).toMatchObject({ tmpDir: TMP, decision: 'keep-dev-shm-tmpdir-too-small' });
+ expect(recorded.logs).toEqual([{ level: 'warn', facts: posture }]);
+ });
+
+ test("measures Chromium's explicit TMPDIR destination", () => {
+ const { statfs, calls } = statfsFrom({
+ [DEV_SHM_PATH]: space(64 * MiB),
+ [TMP]: space(165 * MiB),
+ '/other-mount': space(750 * MiB),
+ });
+ const recorded = effects();
+ const posture = applyDevShmPosture({
+ platform: 'linux',
+ statfs,
+ env: { TMPDIR: '/other-mount' },
+ ...recorded,
+ });
+ expect(calls).toEqual([DEV_SHM_PATH, '/other-mount']);
+ expect(posture.tmpDir).toBe('/other-mount');
+ expect(recorded.switches).toEqual([DISABLE_DEV_SHM_USAGE_SWITCH]);
+ });
+
+ test.each([
+ { tmp: space(165 * MiB), expected: 'keep-dev-shm-tmpdir-too-small' },
+ { tmp: new Error('unreadable'), expected: 'keep-dev-shm-tmpdir-unreadable' },
+ ])('logs $expected at warn without adding a switch', ({ tmp, expected }) => {
+ const { statfs } = statfsFrom({ [DEV_SHM_PATH]: space(64 * MiB), [TMP]: tmp });
+ const recorded = effects();
+ const posture = applyDevShmPosture({
+ platform: 'linux',
+ statfs,
+ env: {},
+ ...recorded,
+ });
+ expect(posture.decision).toBe(expected);
+ expect(recorded.switches).toEqual([]);
+ expect(recorded.logs).toEqual([{ level: 'warn', facts: posture }]);
+ });
+});