Bucket Already Connected

bucket-already-connected · 409

The service already reads a bucket in this environment, or has one staged there, under the variable names this connection would use, so the API staged nothing.

A connection gives the service six variables, S3_ENDPOINT and the rest, or the same names after a prefix, such as UPLOADS_S3_ENDPOINT. prefix is the one asked for, null for the bare names. Applying the changeset answers the same when another bucket took the names after the connect was staged, and then nothing in it is applied.

Besides the members every error carries, this type adds code, serviceId and prefix.

Common causes

  • A second bucket was connected to the service without a prefix, and the first already holds the bare names.
  • The prefix asked for is one another connection on the service in this environment already holds, or one a staged connect takes.

How to fix the call

  • Connect again with a prefix the service doesn't hold: upper case, a letter first, at most 21 characters.
  • List the service's connections in this environment with GET /v1/services/<id>/buckets?environmentId=<environment> to see which prefixes are taken; without environmentId, the call lists production's.
  • To give a connected bucket other names, connect it again with the new prefix: it moves to them.

Example response

json
{
  "type": "bucket-already-connected",
  "title": "Bucket Already Connected",
  "detail": "Service '0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401' already has a bucket connected under the bare S3_* names; pass another prefix",
  "code": "BUCKET_ALREADY_CONNECTED_TO_SERVICE",
  "serviceId": "0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
  "prefix": null,
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/environments/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402/changeset/entries",
  "method": "PUT",
  "instance": "PUT /v1/projects/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/environments/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad402/changeset/entries",
  "status": 409,
  "docs": "https://ghaym.me/docs/errors/bucket-already-connected"
}