Skip to content

Build your personal knowledge base with Trilium Notes

fix(server): give each data directory error one cause and one fix

Elian Dorana153589e12d4
diff --git a/apps/server/src/services/data_dir.spec.ts b/apps/server/src/services/data_dir.spec.ts
index 3346e9ce9c..2fdf7ae91b 100644
--- a/apps/server/src/services/data_dir.spec.ts
+++ b/apps/server/src/services/data_dir.spec.ts
@@ -68,6 +68,41 @@ describe("data_dir.ts unit tests", () => {
});
};
+ type ProcessWithIds = NodeJS.Process & { getuid?: () => number; getgid?: () => number };
+ const proc = process as ProcessWithIds;
+ const originalIds = { getuid: proc.getuid, getgid: proc.getgid };
+
+ // Sets the UID and GID process.getuid()/getgid() report, or removes both as on Windows (null).
+ const stubUser = (id: number | null) => {
+ if (id === null) {
+ delete proc.getuid;
+ delete proc.getgid;
+ } else {
+ proc.getuid = () => id;
+ proc.getgid = () => id;
+ }
+ };
+
+ const restoreUser = () => {
+ if (originalIds.getuid && originalIds.getgid) {
+ proc.getuid = originalIds.getuid;
+ proc.getgid = originalIds.getgid;
+ } else {
+ stubUser(null);
+ }
+ };
+
+ // Runs `run` with process.exit stubbed and returns what was printed before exiting.
+ const runUntilExit = (run: () => unknown) => {
+ const exit = vi.spyOn(process, "exit").mockImplementation(() => {
+ throw new Error("process.exit");
+ });
+ expect(run).toThrow("process.exit");
+ expect(exit).toHaveBeenCalledWith(1);
+ expect(console.error).toHaveBeenCalledTimes(1);
+ return String(vi.mocked(console.error).mock.calls[0][0]);
+ };
+
// helper to set mocked Platform
const setMockPlatform = (osPlatform: string, homedir: string, pathJoin: string) => {
mockFn.osPlatformMock.mockImplementation(() => osPlatform);
@@ -368,8 +403,13 @@ describe("data_dir.ts unit tests", () => {
describe("w/ existing entries", () => {
const W_OK = 2;
- const proc = process as NodeJS.Process & { getuid?: () => number; getgid?: () => number };
- let hadGetuid = false;
+ const blockWrites = (...paths: string[]) => {
+ mockFn.accessSyncMock.mockImplementation((path: string, mode: number) => {
+ if (paths.includes(path) && (mode & W_OK)) {
+ throw new Error("EACCES");
+ }
+ });
+ };
beforeEach(() => {
resetAllMocks();
@@ -377,19 +417,17 @@ describe("data_dir.ts unit tests", () => {
mockFn.pathJoinMock.mockImplementation((...parts: string[]) => parts.join("/"));
mockFn.existsSyncMock.mockReturnValue(true);
mockFn.statSyncMock.mockImplementation((path: string) => ({
- uid: 1000, gid: 1000, mode: path === "/data/log" ? 0o40700 : 0o100644
+ uid: 1000,
+ gid: 1000,
+ mode: path === "/data/log" ? 0o40700 : 0o100644,
+ isFile: () => path !== "/data/log"
}));
vi.spyOn(console, "error").mockImplementation(() => {});
- hadGetuid = "getuid" in proc;
- proc.getuid = () => 1234;
- proc.getgid = () => 1234;
+ stubUser(1234);
});
afterEach(() => {
- if (!hadGetuid) {
- delete proc.getuid;
- delete proc.getgid;
- }
+ restoreUser();
vi.restoreAllMocks();
resetAllMocks();
});
@@ -400,28 +438,34 @@ describe("data_dir.ts unit tests", () => {
expect(console.error).not.toHaveBeenCalled();
});
- it("that the user cannot write – lists them and exits", () => {
- const blocked = new Set([ "/data/document.db", "/data/log", "/data/config.ini" ]);
- mockFn.accessSyncMock.mockImplementation((path: string, mode: number) => {
- if (blocked.has(path) && (mode & W_OK)) {
- throw new Error("EACCES");
- }
- });
- const exit = vi.spyOn(process, "exit").mockImplementation(() => {
- throw new Error("process.exit");
- });
-
- expect(() => getDataDirs("/data")).toThrow("process.exit");
- expect(exit).toHaveBeenCalledWith(1);
- const message = String(vi.mocked(console.error).mock.calls[0][0]);
- expect(message).toContain("Trilium cannot start: the user running it cannot use these files in its data directory.");
- expect(message).toContain("Running as UID:GID 1234:1234.");
- expect(message).toContain("/data/document.db is owned by UID:GID 1000:1000 with permissions 644.");
- expect(message).toContain("/data/log is owned by UID:GID 1000:1000 with permissions 700.");
- expect(message).toContain("for example: sudo chown -R 1234:1234 /data");
+ it("that the user cannot write – lists them with the chown that fixes them and exits", () => {
+ blockWrites("/data/document.db", "/data/log", "/data/config.ini");
+
+ const message = runUntilExit(() => getDataDirs("/data"));
+ expect(message).toContain("Trilium cannot start because it cannot use some of the files in its data directory, /data.");
+ expect(message).toContain([
+ "Trilium runs as UID:GID 1234:1234, but:",
+ " - document.db is owned by UID:GID 1000:1000 with permissions 644",
+ " - log is owned by UID:GID 1000:1000 with permissions 700",
+ ""
+ ].join("\n"));
+ expect(message).toContain(" sudo chown -R 1234:1234 /data");
+ expect(message).toContain("In Docker, the paths above are inside the container.");
// config.ini is only read, so a denied write must not flag it.
expect(message).not.toContain("config.ini");
});
+
+ it("on Windows – says which files are read-only, without UIDs or a chown", () => {
+ stubUser(null);
+ blockWrites("/data/document.db");
+ mockFn.statSyncMock.mockImplementation(() => ({ uid: 0, gid: 0, mode: 0o100444, isFile: () => true }));
+
+ const message = runUntilExit(() => getDataDirs("/data"));
+ expect(message).toContain("The user running Trilium cannot use them:\n - document.db is read-only\n");
+ expect(message).toContain("give the user running Trilium full control of the data directory");
+ expect(message).not.toContain("UID:GID");
+ expect(message).not.toContain("sudo");
+ });
});
});
@@ -430,10 +474,12 @@ describe("data_dir.ts unit tests", () => {
resetAllMocks();
process.env.TRILIUM_DATA_DIR = "/home/mock/trilium-data-ERR";
vi.spyOn(console, "error").mockImplementation(() => {});
+ stubUser(1000);
});
afterEach(() => {
delete process.env.TRILIUM_DATA_DIR;
+ restoreUser();
vi.restoreAllMocks();
});
@@ -444,65 +490,62 @@ describe("data_dir.ts unit tests", () => {
return err;
};
- // Runs getTriliumDataDir with process.exit stubbed and returns what was printed.
- const runUntilExit = () => {
- const exit = vi.spyOn(process, "exit").mockImplementation(() => {
- throw new Error("process.exit");
- });
- expect(() => getTriliumDataDir("trilium-data")).toThrow("process.exit");
- expect(exit).toHaveBeenCalledWith(1);
- expect(console.error).toHaveBeenCalledTimes(1);
- return String(vi.mocked(console.error).mock.calls[0][0]);
- };
+ const ownedByRoot = () => ({ uid: 0, gid: 0, mode: 0o40755, isFile: () => false });
- it("EACCES – prints why the directory cannot be created and exits", () => {
+ it("EACCES creating the data directory – suggests creating it for the user and exits", () => {
mkdirThrows("EACCES");
- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o755 }));
- // Provide getuid/getgid (absent on Windows) so the UID:GID line is printed.
- const proc = process as NodeJS.Process & { getuid?: () => number; getgid?: () => number };
- const hadGetuid = "getuid" in proc;
- proc.getuid = () => 1000;
- proc.getgid = () => 1000;
+ mockFn.statSyncMock.mockImplementation(ownedByRoot);
+
+ const message = runUntilExit(() => getTriliumDataDir("trilium-data"));
+ expect(message).toContain("Trilium cannot start because it cannot create /home/mock/trilium-data-ERR.");
+ expect(message).toContain("Trilium runs as UID:GID 1000:1000, which cannot write to /home/mock: it is owned by UID:GID 0:0 with permissions 755.");
+ expect(message).toContain(" sudo mkdir -p /home/mock/trilium-data-ERR && sudo chown 1000:1000 /home/mock/trilium-data-ERR");
+ expect(message).toContain("Or set TRILIUM_DATA_DIR to a directory that user owns.");
+ expect(message).toContain("In Docker, the paths above are inside the container.");
+ expect(message).not.toContain("chown -R");
+ });
- try {
- const message = runUntilExit();
- expect(message).toContain("Trilium cannot start: permission denied while creating /home/mock/trilium-data-ERR.");
- expect(message).toContain("Running as UID:GID 1000:1000.");
- expect(message).toContain("/home/mock is owned by UID:GID 1000:1000 with permissions 755.");
- expect(message).toContain("in Docker, set USER_UID and USER_GID to the owner of the mounted directory");
- expect(mockFn.statSyncMock).toHaveBeenCalledWith("/home/mock");
- } finally {
- if (!hadGetuid) {
- delete proc.getuid;
- delete proc.getgid;
- }
- }
+ it("EACCES creating a directory inside the data directory – suggests a chown of the data directory and exits", () => {
+ delete process.env.TRILIUM_TMP_DIR;
+ mockFn.pathJoinMock.mockImplementation((...parts: string[]) => parts.join("/"));
+ mkdirThrows("EACCES");
+ mockFn.statSyncMock.mockImplementation(ownedByRoot);
+
+ const message = runUntilExit(() => getDataDirs("/data"));
+ expect(message).toContain("Trilium cannot start because it cannot create /data/tmp.");
+ expect(message).toContain("Trilium runs as UID:GID 1000:1000, which cannot write to its data directory, /data: it is owned by UID:GID 0:0 with permissions 755.");
+ expect(message).toContain(" sudo chown -R 1000:1000 /data");
+ expect(message).not.toContain("mkdir");
});
it("EACCES – names the ancestor that cannot be entered and exits", () => {
+ stubUser(1234);
mkdirThrows("EACCES");
mockFn.accessSyncMock.mockImplementation((path: string) => {
if (path === "/home/mock") {
throw new Error("EACCES");
}
});
- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o700 }));
+ mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o40700, isFile: () => false }));
- const message = runUntilExit();
- expect(message).toContain("Trilium cannot start: /home/mock/trilium-data-ERR cannot be reached.");
- expect(message).toContain("/home/mock cannot be entered; it is owned by UID:GID 1000:1000 with permissions 700.");
+ const message = runUntilExit(() => getTriliumDataDir("trilium-data"));
+ expect(message).toContain("Trilium cannot start because it cannot reach /home/mock/trilium-data-ERR.");
+ expect(message).toContain("Trilium runs as UID:GID 1234:1234, which cannot enter /home/mock: it is owned by UID:GID 1000:1000 with permissions 700.");
+ expect(message).toContain(" sudo chmod o+x /home/mock");
+ expect(mockFn.statSyncMock).toHaveBeenCalledWith("/home/mock");
});
it("EACCES – reports a parent that cannot be inspected and exits", () => {
mkdirThrows("EACCES");
mockFn.statSyncMock.mockImplementation(() => { throw new Error("no access"); });
- expect(runUntilExit()).toContain("/home/mock cannot be inspected.");
+ expect(runUntilExit(() => getTriliumDataDir("trilium-data")))
+ .toContain("which cannot write to /home/mock: it cannot be inspected.");
});
it("EACCES under Electron – throws the explanation for the main-process error dialog", () => {
const err = mkdirThrows("EACCES");
- mockFn.statSyncMock.mockImplementation(() => ({ uid: 1000, gid: 1000, mode: 0o755 }));
+ mockFn.statSyncMock.mockImplementation(ownedByRoot);
const exit = vi.spyOn(process, "exit");
Object.defineProperty(process.versions, "electron", { value: "1.0.0", configurable: true });
@@ -514,7 +557,9 @@ describe("data_dir.ts unit tests", () => {
thrown = e;
}
expect(thrown).toBeInstanceOf(Error);
- expect((thrown as Error).message).toContain("Trilium cannot start: permission denied while creating /home/mock/trilium-data-ERR.");
+ const message = (thrown as Error).message;
+ expect(message).toContain("Trilium cannot start because it cannot create /home/mock/trilium-data-ERR.");
+ expect(message).not.toContain("In Docker");
expect((thrown as Error).cause).toBe(err);
expect(exit).not.toHaveBeenCalled();
} finally {
diff --git a/apps/server/src/services/data_dir.ts b/apps/server/src/services/data_dir.ts
index b49555a0fa..b2051f525e 100644
--- a/apps/server/src/services/data_dir.ts
+++ b/apps/server/src/services/data_dir.ts
@@ -53,7 +53,7 @@ export function getDataDirs(TRILIUM_DATA_DIR: string) {
OCR_CACHE_DIR: process.env.TRILIUM_OCR_CACHE_DIR || pathJoin(TRILIUM_DATA_DIR, "ocr-cache")
} as const;
- createDirIfNotExisting(dataDirs.TMP_DIR);
+ createDirIfNotExisting(dataDirs.TMP_DIR, TRILIUM_DATA_DIR);
checkExistingEntries(dataDirs);
Object.freeze(dataDirs);
@@ -98,26 +98,19 @@ function checkExistingEntries(dataDirs: ReturnType<typeof getDataDirs>) {
return;
}
+ const dataDir = dataDirs.TRILIUM_DATA_DIR;
const user = getProcessUser();
- const lines = [
- "Trilium cannot start: the user running it cannot use these files in its data directory.",
- ""
- ];
- if (user) {
- lines.push(`Running as UID:GID ${user}.`);
- }
- for (const [ path ] of unusable) {
- lines.push(`${path} ${describeOwnership(path)}.`);
- }
- lines.push("", "To fix this, give the data directory and everything in it to the user running Trilium,");
- if (user) {
- lines.push(`for example: sudo chown -R ${user} ${dataDirs.TRILIUM_DATA_DIR}`);
- }
- lines.push(
- "In Docker, run that on the host directory mounted as the data directory, or start the",
- "container without --user."
- );
- stopStartup(lines.join("\n"));
+ stopStartup([
+ `Trilium cannot start because it cannot use some of the files in its data directory, ${dataDir}.`,
+ "",
+ user ? `Trilium runs as UID:GID ${user}, but:` : "The user running Trilium cannot use them:",
+ ...unusable.map(([ path ]) => ` - ${relativeToDir(path, dataDir)} ${describeOwnership(path)}`),
+ "",
+ ...(user
+ ? [ "To fix this, give the data directory and everything in it to that user:", ` sudo chown -R ${user} ${dataDir}` ]
+ : [ "To fix this, give the user running Trilium full control of the data directory and everything in it." ]),
+ ...containerHint()
+ ].join("\n"));
}
export function getPlatformAppDataDir(platform: ReturnType<typeof os.platform>, ENV_APPDATA_DIR: string | undefined = process.env.APPDATA) {
@@ -157,47 +150,94 @@ function getProcessUser() {
}
}
-/** Completes a sentence about `path`: "is owned by UID:GID 1000:1000 with permissions 700". */
+/**
+ * Completes a sentence about `path`: "is owned by UID:GID 1000:1000 with permissions 700". Windows
+ * has no UIDs, and `fs.statSync()` reports 0 there, so it only says whether a file is read-only.
+ */
function describeOwnership(path: string) {
try {
const stats = fs.statSync(path);
+ if (!getProcessUser()) {
+ return stats.isFile() && !(stats.mode & 0o200) ? "is read-only" : "cannot be accessed";
+ }
return `is owned by UID:GID ${stats.uid}:${stats.gid} with permissions ${(stats.mode & 0o777).toString(8)}`;
} catch {
return "cannot be inspected";
}
}
-function failWithPermissionError(targetPath: fs.PathLike, cause: unknown): never {
- stopStartup(describePermissionError(targetPath.toString()), cause);
+/**
+ * The paths in a message are the ones Trilium sees, which in a container are not the host paths a
+ * fix has to be applied to. Desktop never runs in a container, so its dialog leaves this out.
+ */
+function containerHint() {
+ if (process.versions.electron) {
+ return [];
+ }
+ return [
+ "",
+ "In Docker, the paths above are inside the container. Apply the fix to the directory mounted",
+ "there from the host, or start the container without --user."
+ ];
+}
+
+function relativeToDir(path: string, dir: string) {
+ const separator = path.charAt(dir.length);
+ return path.startsWith(dir) && (separator === "/" || separator === "\\") ? path.slice(dir.length + 1) : path;
}
-function describePermissionError(path: string) {
- const blockedDir = findUnreachableAncestor(dirname(path));
- const shownDir = blockedDir ?? dirname(path);
+function failWithPermissionError(targetPath: fs.PathLike, dataDir: string | undefined, cause: unknown): never {
+ stopStartup(describePermissionError(targetPath.toString(), dataDir), cause);
+}
+
+/**
+ * Explains why `path` cannot be created. `dataDir` is the data directory `path` belongs in, or
+ * `undefined` when `path` is the data directory itself.
+ */
+function describePermissionError(path: string, dataDir: string | undefined) {
+ const parent = dirname(path);
+ const blockedDir = findUnreachableAncestor(parent);
const user = getProcessUser();
- const lines = [
- blockedDir
- ? `Trilium cannot start: ${path} cannot be reached.`
- : `Trilium cannot start: permission denied while creating ${path}.`,
- ""
- ];
- if (user) {
- lines.push(`Running as UID:GID ${user}.`);
- }
- lines.push(blockedDir
- ? `${shownDir} cannot be entered; it ${describeOwnership(shownDir)}.`
- : `${shownDir} ${describeOwnership(shownDir)}.`);
+ const subject = user ? `Trilium runs as UID:GID ${user}, which` : "The user running Trilium";
- lines.push(
- "",
- "To fix this, either:",
- " - make sure the user running Trilium can enter every directory above the data directory",
- " and write to the data directory itself",
- " - set TRILIUM_DATA_DIR to a directory owned by that user",
- " - in Docker, set USER_UID and USER_GID to the owner of the mounted directory, or, if the",
- " container runs with --user, give the mounted directory to that user"
- );
- return lines.join("\n");
+ let lines: string[];
+ if (blockedDir) {
+ lines = [
+ `Trilium cannot start because it cannot reach ${path}.`,
+ "",
+ `${subject} cannot enter ${blockedDir}: it ${describeOwnership(blockedDir)}.`,
+ "",
+ ...(user
+ ? [ "To fix this, let that user enter it:", ` sudo chmod o+x ${blockedDir}` ]
+ : [ `To fix this, let the user running Trilium enter ${blockedDir}.` ]),
+ "Or set TRILIUM_DATA_DIR to a directory that user can reach."
+ ];
+ } else if (parent === dataDir) {
+ lines = [
+ `Trilium cannot start because it cannot create ${path}.`,
+ "",
+ `${subject} cannot write to its data directory, ${parent}: it ${describeOwnership(parent)}.`,
+ "",
+ ...(user
+ ? [ "To fix this, give the data directory and everything in it to that user:", ` sudo chown -R ${user} ${parent}` ]
+ : [ "To fix this, give the user running Trilium full control of the data directory." ]),
+ "Or set TRILIUM_DATA_DIR to a directory that user owns."
+ ];
+ } else {
+ lines = [
+ `Trilium cannot start because it cannot create ${path}.`,
+ "",
+ `${subject} cannot write to ${parent}: it ${describeOwnership(parent)}.`,
+ "",
+ ...(user
+ ? [ "To fix this, create the directory for that user:", ` sudo mkdir -p ${path} && sudo chown ${user} ${path}` ]
+ : [ "To fix this, create the directory and give the user running Trilium full control of it." ])
+ ];
+ if (!dataDir) {
+ lines.push("Or set TRILIUM_DATA_DIR to a directory that user owns.");
+ }
+ }
+ return [ ...lines, ...containerHint() ].join("\n");
}
/**
@@ -218,15 +258,16 @@ function findUnreachableAncestor(dir: string) {
}
}
-function createDirIfNotExisting(path: fs.PathLike, permissionMode: fs.Mode = FOLDER_PERMISSIONS) {
+/** `dataDir` is the data directory `path` belongs in, or `undefined` when `path` is the data directory. */
+function createDirIfNotExisting(path: fs.PathLike, dataDir?: string) {
try {
- fs.mkdirSync(path, permissionMode);
+ fs.mkdirSync(path, FOLDER_PERMISSIONS);
} catch (err: unknown) {
if (err && typeof err === "object" && "code" in err) {
const code = (err as { code: string }).code;
if (code === "EACCES") {
- failWithPermissionError(path, err);
+ failWithPermissionError(path, dataDir, err);
} else if (code === "EEXIST") {
// Directory already exists - verify it's actually a directory
try {