laurent22/joplin · error · Error

Cannot initialise synchroniser.

Error message

Cannot initialise synchroniser.

What it means

Thrown by `sync` when `syncTarget.synchronizer()` returns a falsy value, meaning the sync target could not build a working Synchronizer instance. By this point authentication has already succeeded, so the failure is in target setup — typically a missing/invalid auth token, unsupported sync target, or an API client construction error that the target swallowed and returned null for.

Source

Thrown at packages/app-cli/app/command-sync.ts:193

				app().gui().showConsole();
				app().gui().maximizeConsole();

				const authDone = await this.doAuth();
				if (!authDone) return cleanUp();
			}

			const sync = await syncTarget.synchronizer();

			const options: SyncStartOptions = {
				onProgress: (report) => {
					const lines = Synchronizer.reportToLines(report);
					if (lines.length) cliUtils.redraw(lines.join(' '));
				},
			};

			this.stdout(_('Synchronisation target: %s (%s)', Setting.enumOptionLabel('sync.target', this.syncTargetId_), this.syncTargetId_));

			if (!sync) throw new Error(_('Cannot initialise synchroniser.'));

			if (args.options.upgrade) {
				let migrationError = null;

				try {
					const migrationHandler = new MigrationHandler(
						sync.api(),
						reg.db(),
						sync.lockHandler(),
						appTypeToLockType(Setting.value('appType')),
						Setting.value('clientId'),
					);

					migrationHandler.setLogger(cliUtils.stdoutLogger(this.stdout.bind(this)));

					await migrationHandler.upgrade();
				} catch (error) {
					migrationError = error;

View on GitHub (pinned to 2654b33620)

Solutions

1. Re-run authentication for the target: `:sync` will trigger `doAuth()` if `isAuthenticated` is false — but if it returns true yet synchronizer() is null, force re-auth by clearing `sync.<id>.auth`.
2. Verify `sync.target` points to a supported id (3=OneDrive, 5=Dropbox, 7=WebDAV, 9=File system, 10=Joplin Cloud, etc.).
3. Check the log output for the underlying api() error that caused synchronizer() to return null.
4. If using Joplin Server, confirm `sync.10.path` is reachable and the API token/credentials are valid.

Example fix

// before
if (!sync) throw new Error(_('Cannot initialise synchroniser.'));

// after - surface the underlying cause if available
if (!sync) throw new Error(_('Cannot initialise synchroniser for target %s (%s). Check sync.%s.auth and re-authenticate.', Setting.enumOptionLabel('sync.target', this.syncTargetId_), this.syncTargetId_, this.syncTargetId_));

const sync = await syncTarget.synchronizer();
if (!sync) {
	throw new Error(`Synchroniser for target ${Setting.value('sync.target')} is null. Verify auth and sync.target config.`);
}

null

try {
	await sync();
} catch (e) {
	if (/Cannot initialise synchroniser/.test(e.message)) { /* clear sync.<id>.auth, re-run doAuth, retry */ }
	else throw e;
}

When it happens

Trigger: Configuring `sync.target` to a value whose SyncTargetRegistry entry cannot produce a synchronizer (e.g. missing OneDrive/Dropbox auth JSON even though `isAuthenticated` passed), or pointing at an incompatible/unsupported target id. Also possible if the target's api() threw internally and the implementation returned null.

Common situations: First-time sync setup where credentials were partially provided; switching `sync.target` without re-authenticating; a corrupted `sync.<id>.auth` setting string; using a sync target plugin that failed to load.

Related errors

• Please specify the sync target path.
• No text editor is defined. Please set it using `config edito
• Synchronisation is already in progress.
• Got metadata for path but could not fetch content: ${path}
• Invalid WebDAV resource format: ${JSON.stringify(resource)}

AI-assisted analysis of laurent22/joplin@2654b33620 (2026-08-12). Data as JSON: /api/errors/cbe1ea964aa212b0. Report an issue: GitHub.