Dokploy/dokploy · error · TRPCError

UNAUTHORIZED

UNAUTHORIZED

Error message

You need to use a server to create a Postgres

What it means

Thrown by the createPostgres tRPC mutation when the deployment is Dokploy Cloud (IS_CLOUD) or the web server settings have remoteServersOnly enabled, but the request did not include a serverId. Dokploy requires databases to be pinned to an explicit server in these modes instead of defaulting to the local/web server.

Source

Thrown at apps/dokploy/server/api/routers/postgres.ts:72

} from "@/server/db/schema";
import { cancelJobs } from "@/server/utils/backup";

export const postgresRouter = createTRPCRouter({
	create: protectedProcedure
		.input(apiCreatePostgres)
		.mutation(async ({ input, ctx }) => {
			try {
				const environment = await findEnvironmentById(input.environmentId);
				const project = await findProjectById(environment.projectId);

				await checkServiceAccess(ctx, project.projectId, "create");

				const webServerSettings = await getWebServerSettings();
				if (
					(IS_CLOUD || webServerSettings?.remoteServersOnly) &&
					!input.serverId
				) {
					throw new TRPCError({
						code: "UNAUTHORIZED",
						message: "You need to use a server to create a Postgres",
					});
				}

				if (project.organizationId !== ctx.session.activeOrganizationId) {
					throw new TRPCError({
						code: "UNAUTHORIZED",
						message: "You are not authorized to access this project",
					});
				}

				if (input.serverId) {
					const accessibleIds = await getAccessibleServerIds(ctx.session);
					if (!accessibleIds.has(input.serverId)) {
						throw new TRPCError({
							code: "UNAUTHORIZED",
							message: "You are not authorized to access this server",

View on GitHub (pinned to 546686ea35)

Solutions

1. Pass a serverId in the create request payload (e.g. from the servers dropdown / server.list API)
2. If self-hosted and this is unexpected, check Settings > Web Server and disable remoteServersOnly
3. Ensure the user has access to at least one server before creating a Postgres instance

Example fix

// before
const pg = await api.postgres.create.mutate({ name: 'db', projectId, envId });
// after
const pg = await api.postgres.create.mutate({ name: 'db', projectId, envId, serverId: selectedServerId });

const servers = await api.server.list.query();
if ((isCloud || settings.remoteServersOnly) && servers.length === 0) {
  throw new Error('No servers available — cannot create Postgres');
}
const payload = { ...input, serverId: input.serverId ?? servers[0]?.serverId };

When it happens

Trigger: Calling postgres.create without input.serverId while IS_CLOUD=true or when getWebServerSettings() returns remoteServersOnly=true. Typically happens when a client built against self-hosted Dokploy (where serverId is optional) is used against Dokply Cloud.

Common situations: Self-hosted scripts/API clients reused against the cloud version; admin enabled 'remote servers only' in web server settings; frontend not sending the server selector value.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• NOT_FOUND
• UNAUTHORIZED
• UNAUTHORIZED
• UNAUTHORIZED
• FORBIDDEN

AI-assisted analysis of Dokploy/dokploy@546686ea35 (2026-08-27). Data as JSON: /api/errors/77b4ffc41dfaeadc. Report an issue: GitHub.