Skip to content

VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.

fix(windows): update locked runtime folders in place; clearer missing-environment message

velixio897be996c497
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abbe0d4ad..9f33ca692 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,10 @@ metadata and the backend fallback mirror it.
- Preview iOS and Android companion apps: drive your own VoiceStudio from your phone (speak, voices and cloning, dubbing, dictation) after pairing by QR code; build from source for now ([guide](docs/mobile.md)) (#2965)
+### Fixed
+
+- Windows runtime refresh no longer fails with `EPERM` on a locked backend folder (OneDrive, antivirus): it updates the files in place; the missing-Python-environment message now names the exact folder and tells non-checkout installs to use the installer (#PR) — thanks @afraniohugo, @javalovelinux-cmd and @eduardpp00!
+
### Docs
- Contributor guides and the pull request template explain how to sign the CLA before opening a first pull request (#2676)
diff --git a/docs/install/troubleshooting.md b/docs/install/troubleshooting.md
index a11e1cc23..a982401b3 100644
--- a/docs/install/troubleshooting.md
+++ b/docs/install/troubleshooting.md
@@ -1334,13 +1334,14 @@ the message:
slowest because antivirus scans every new file; later starts are much faster.
- **`The Python environment in <folder> is missing`** or **`… is incomplete:
<reason>`** (running from a source checkout) — run `bun run setup:api` in the
- repository and let it finish. *Missing* means no `.venv` exists yet.
+ repository and let it finish (the message names the folder to open the terminal in; it is never taken from the terminal's working directory, so running from `C:\Windows\System32` does not matter). A folder without `pyproject.toml` is not a source checkout: install from the release installer instead. *Missing* means no `.venv` exists yet.
*Incomplete* quotes the import that failed, e.g. `ModuleNotFoundError: No
module named 'sentencepiece'` (setup did not finish: rerun it) or `ImportError:
DLL load failed` (Windows: rerun setup, which installs the Visual C++
runtime). If the folder is inside OneDrive, Dropbox, iCloud Drive or Google
Drive, move the checkout to a plain local folder first: online-only
- placeholders and file locking break the Python environment.
+ placeholders and file locking break the Python environment. The same applies to `error loading dynamically imported module: http://localhost:3902/@fs/…/node_modules/.vite/deps/…` from a dev server running inside OneDrive (installed builds never load from a dev server).
+- **`EPERM: operation not permitted, rename …\.previous-backend`** — a scanner or OneDrive held the runtime folder while VoiceStudio refreshed it. The app retries for about 10 s, then updates the files in place; if it still fails, exclude the runtime folder from antivirus and quit any VoiceStudio left in Task Manager.
A native crash (`3221225477`, `-1073741819`) right after pressing Generate
shortly after launch was caused by the startup preload and the first generation
diff --git a/electron/src/main/backend-launch.test.ts b/electron/src/main/backend-launch.test.ts
index f4ef7fd9c..40f8b1f13 100644
--- a/electron/src/main/backend-launch.test.ts
+++ b/electron/src/main/backend-launch.test.ts
@@ -1,7 +1,7 @@
// @vitest-environment node
import { afterEach, expect, it, vi } from 'vitest';
import { join, resolve } from 'node:path';
-const state = vi.hoisted(() => ({ installed: true, packaged: false, ready: true }));
+const state = vi.hoisted(() => ({ installed: true, packaged: false, ready: true, checkout: true }));
vi.mock('electron', () => ({
app: {
get isPackaged() {
@@ -15,7 +15,7 @@ vi.mock('node:fs', async (importOriginal) => ({
...(await importOriginal<typeof import('node:fs')>()),
existsSync: (path: string) =>
path === join(resolve('/repo'), 'backend', 'main.py') ||
- path === join(resolve('/repo'), 'pyproject.toml') ||
+ (path === join(resolve('/repo'), 'pyproject.toml') && state.checkout) ||
(path.includes('.venv') ? state.installed : path.includes('uv')),
statSync: () => ({ isFile: () => true, size: 1 }),
accessSync: () => undefined,
@@ -44,6 +44,7 @@ afterEach(() => {
state.installed = true;
state.ready = true;
state.packaged = false;
+ state.checkout = true;
vi.unstubAllEnvs();
});
it('launches the prepared source interpreter without syncing or downloading dependencies', async () => {
@@ -98,6 +99,16 @@ it('names the failing import or the absent interpreter instead of one vague mess
expect(missing.error).not.toContain('incomplete');
});
+it('names the folder to open and refuses setup advice outside a checkout (#2988)', async () => {
+ vi.stubEnv('OMNIVOICE_BACKEND_CMD', '');
+ state.installed = false;
+ state.checkout = false;
+ const plan = await resolveSpawnPlan(3900);
+ if (!('error' in plan)) throw new Error('expected a setup error');
+ expect(plan.error).toContain('not a VoiceStudio source checkout');
+ expect(plan.error).toContain('release installer');
+});
+
it('keeps native fault frames when the production log ring overflows', async () => {
const { BackendSupervisor } = await import('./backend');
const supervisor = new BackendSupervisor();
diff --git a/electron/src/main/backend.ts b/electron/src/main/backend.ts
index 00a336857..283e2d049 100644
--- a/electron/src/main/backend.ts
+++ b/electron/src/main/backend.ts
@@ -415,8 +415,17 @@ export async function resolveSpawnPlan(
// deadline and repeat that download after every restart (#2184).
const portArg = ['--port', String(port)];
const python = venvPython(root);
- const setup = 'Run `bun run setup:api` in the repository, wait for it to finish, then restart.';
+ const setup = `Open a terminal in ${root}, run \`bun run setup:api\`, wait for it to finish, then restart.`;
if (!existsSync(python)) {
+ // Not a source checkout and not a packaged app (a copied folder, a
+ // download of the wrong archive): setup:api does not exist there (#2988).
+ if (!existsSync(join(root, 'pyproject.toml'))) {
+ return {
+ error:
+ `The Python environment in ${root} is missing (no ${relative(root, python)}), and this is not a VoiceStudio source checkout. ` +
+ 'Install VoiceStudio from the release installer, or clone the repository and run `bun run setup:api` inside it.',
+ };
+ }
return {
error: `The Python environment in ${root} is missing (no ${relative(root, python)}). ${setup}`,
};
diff --git a/electron/src/main/runtime-project.test.ts b/electron/src/main/runtime-project.test.ts
index 9e6a9b411..3e40a5e87 100644
--- a/electron/src/main/runtime-project.test.ts
+++ b/electron/src/main/runtime-project.test.ts
@@ -532,6 +532,26 @@ describe('packaged runtime setup', () => {
expect(await readFile(runtimePython(project), 'utf8')).toBe('interpreter');
expect(await readFile(join(project, 'personal.txt'), 'utf8')).toBe('preserve');
});
+ it('falls back to an in-place copy when Windows keeps a folder locked (#3010, #2669)', async () => {
+ const { bundle, project } = await fixture();
+ await stageRuntimeSources(bundle, project);
+ await writeFile(join(project, 'backend', 'obsolete.py'), 'old');
+ await writeFile(join(bundle, 'backend', 'main.py'), 'new');
+ const locked = async () => {
+ throw Object.assign(new Error('EPERM: operation not permitted, rename'), { code: 'EPERM' });
+ };
+ await stageRuntimeSources(bundle, project, locked);
+ expect(await readFile(join(project, 'backend', 'main.py'), 'utf8')).toBe('new');
+ expect(existsSync(join(project, 'backend', 'obsolete.py'))).toBe(false);
+ expect(existsSync(join(project, '.incoming-backend'))).toBe(false);
+ });
+ it('still fails on a rename error that is not a lock', async () => {
+ const { bundle, project } = await fixture();
+ const broken = async () => {
+ throw Object.assign(new Error('ENOSPC'), { code: 'ENOSPC' });
+ };
+ await expect(stageRuntimeSources(bundle, project, broken)).rejects.toThrow('ENOSPC');
+ });
it('does not leave a ready marker after a failed repair', async () => {
const { bundle, project } = await fixture();
await installRuntime(
diff --git a/electron/src/main/runtime-project.ts b/electron/src/main/runtime-project.ts
index f5fa1ab5e..f60f49f65 100644
--- a/electron/src/main/runtime-project.ts
+++ b/electron/src/main/runtime-project.ts
@@ -464,8 +464,34 @@ export async function runtimeCompatible(bundle: string, project: string): Promis
}
}
+const LOCKED = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/** Mirror `source` onto `target` file by file, for a folder Windows will not rename
+ * (a scanner, OneDrive or a lingering backend holds a handle inside it, #3010, #2669).
+ * Files can be overwritten where a folder rename cannot; files the new bundle no
+ * longer ships are pruned best-effort. */
+async function mirrorInPlace(source: string, target: string): Promise<void> {
+ await cp(source, target, { recursive: true, force: true });
+ const walk = async (rel: string): Promise<void> => {
+ for (const entry of await readdir(join(target, rel), { withFileTypes: true })) {
+ const next = join(rel, entry.name);
+ const kept = await stat(join(source, next)).then(
+ () => true,
+ () => false,
+ );
+ if (!kept) await rm(join(target, next), { recursive: true, force: true }).catch(() => {});
+ else if (entry.isDirectory()) await walk(next);
+ }
+ };
+ await walk('').catch(() => {});
+}
+
/** Replace only bundled code. The interpreter, models and user data are never removed. */
-export async function stageRuntimeSources(bundle: string, project: string): Promise<void> {
+export async function stageRuntimeSources(
+ bundle: string,
+ project: string,
+ rename: typeof renameWithRetry = renameWithRetry,
+): Promise<void> {
await mkdir(project, { recursive: true });
for (const name of SOURCES) {
const target = join(project, name);
@@ -477,20 +503,26 @@ export async function stageRuntimeSources(bundle: string, project: string): Prom
filter: (source) => !source.split(/[\\/]/).includes('__pycache__'),
});
await rm(previous, { recursive: true, force: true });
- let moved = false;
try {
- await renameWithRetry(target, previous, DIRECTORY_RENAME);
- moved = true;
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
- }
- try {
- await renameWithRetry(pending, target, DIRECTORY_RENAME);
+ let moved = false;
+ try {
+ await rename(target, previous, DIRECTORY_RENAME);
+ moved = true;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+ }
+ try {
+ await rename(pending, target, DIRECTORY_RENAME);
+ } catch (error) {
+ if (moved) await rename(previous, target, DIRECTORY_RENAME);
+ throw error;
+ }
} catch (error) {
- if (moved) await renameWithRetry(previous, target, DIRECTORY_RENAME);
- throw error;
+ if (!LOCKED.has((error as NodeJS.ErrnoException).code ?? '')) throw error;
+ await mirrorInPlace(pending, target);
}
- await rm(previous, { recursive: true, force: true });
+ await rm(pending, { recursive: true, force: true }).catch(() => {});
+ await rm(previous, { recursive: true, force: true }).catch(() => {});
}
}