paperclipai/paperclip · error

Failed to ensure local environment

Error message

Failed to ensure local environment

What it means

Unexpected-outcome guard in ensureLocalEnvironment: after a unique-name insert race on environments_name_idx, the fallback select for an existing local-driver row also found nothing. The local environment should be guaranteed after this path, so its absence is an invariant violation and the service fails.

Source

Thrown at server/src/services/environments.ts:908

            where: sql`${environments.driver} = 'local'`,
          })
          .returning()
          .then((rows) => rows[0] ?? null);
      const row = await insert().catch((error: unknown) => {
        if (hasConstraintName(error, "environments_name_idx")) {
          return null;
        }
        throw error;
      });
      if (row) return toEnvironment(row);

      const existing = await db
        .select()
        .from(environments)
        .where(eq(environments.driver, "local"))
        .then((rows) => rows[0] ?? null);
      if (!existing) {
        throw new Error("Failed to ensure local environment");
      }
      const existingMetadata = (existing.metadata ?? {}) as Record<string, unknown>;
      if (isCloudManagedInstance() && existingMetadata.managedByPaperclip !== true) {
        const adopted = await db
          .update(environments)
          .set({
            metadata: { ...existingMetadata, managedByPaperclip: true },
            updatedAt: new Date(),
          })
          .where(eq(environments.id, existing.id))
          .returning()
          .then((rows) => rows[0] ?? existing);
        return toEnvironment(adopted);
      }
      return toEnvironment(existing);
    },

    ensureManagedSandboxEnvironment,

View on GitHub (pinned to 01ad858492)

Solutions

1. Check server logs for the failure ensuring the local environment (path, permissions), then retry.

When it happens

Trigger: Thrown at server/src/services/environments.ts:908 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/060b2994d49af636. Report an issue: GitHub.