# Limits & Rules (/connectors/gcp-pub-sub/reference/limits-and-rules)



Two kinds of limit apply to the connector: **Google-exact rules** (fixed, not configurable — the
connector enforces the same values real Pub/Sub does) and **connector config caps** (the
`CONNECTORS_GCP_*` settings that tune DoS guards and defaults). Both are listed here; the full prose
walkthrough of the config caps lives in [Configuration](/connectors/gcp-pub-sub/concepts/configuration).

## Google-exact rules (not configurable) [#google-exact-rules-not-configurable]

| Rule                    | Value                                                                                                                                                    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resource id             | 3..255 chars, must start with a letter, charset `[A-Za-z0-9._~%+-]`, no `goog` prefix; **topic ids may not start with `sub.`** (reserved namespace) |
| Message size            | ≤ 10 MiB total (body + attributes)                                                                                                                       |
| Batch size              | ≤ 1000 messages                                                                                                                                          |
| Attributes              | ≤ 100 per message; key ≤ 256 B (no `goog`); value ≤ 1024 B; ordering key ≤ 1024 B                                                                        |
| Ack deadline            | `0` (nack) or **10..600 s**                                                                                                                              |
| Retention               | 10 min .. 31 days, **clamped to the broker maximum**                                                                                                     |
| `max_delivery_attempts` | **5..100** (`0` = unset)                                                                                                                                 |
| Filter                  | attributes-only CEL-subset, ≤ 256 chars, immutable (compiled at create)                                                                                  |
| Schema definition       | ≤ 300 KB                                                                                                                                                 |

A violation of any of these is reported as a Google-shaped gRPC error (`INVALID_ARGUMENT` for most;
see [Error Codes](/connectors/gcp-pub-sub/reference/error-codes)).

### Notes on the tricky ones [#notes-on-the-tricky-ones]

* **Resource id grammar (gotcha #7).** Ids must *start with a letter*; a topic id that starts with
  `sub.` collides with the subscription-queue namespace (`gcp.sub.{s}`) and is rejected. A
  subscription id may not contain the reserved `.k.` / `.h.` infixes (the per-ordering-key channel
  namespace). The charset allows `._~%+-` but not `/` or spaces.
* **Retention clamp (gotcha #5).** You may request 10 min..31 days, but the effective retention is
  capped at the broker's global maximum. `GetTopic` / `GetSubscription` **echo your requested value**,
  while fan-out, `Seek`, and the dashboard use the **clamped** value. If retention matters for `Seek`,
  check the broker ceiling, not the topic config.
* **`max_delivery_attempts` (gotcha #6).** Dead-letter requires 5..100; values 1..4 are rejected.
  `0` means "no dead-letter policy" (unset), not "deliver zero times".
* **Batch atomicity.** The full batch is validated before *anything* is enqueued; the first
  offending message rejects the entire `Publish` with `INVALID_ARGUMENT` and nothing is published.
* **Attributes / ordering key sizing.** A message must have **`data` or `attributes` non-empty**.
  Attribute keys beginning `goog` are reserved by Google and rejected.

## Connector config caps (`CONNECTORS_GCP_*`) [#connector-config-caps-connectors_gcp_]

Server-side settings in `[Connectors.Gcp]`; env vars use the `CONNECTORS_GCP_*` prefix. Defaults
shown are the connector defaults.

| Field                        | Env var                                        | Default             | Meaning / constraint                                                                                                            |
| ---------------------------- | ---------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `Enable`                     | `CONNECTORS_GCP_ENABLE`                        | `true`              | Default-on; `false` disables (closes port 8085)                                                                                 |
| `Port`                       | `CONNECTORS_GCP_PORT`                          | `"8085"`            | gRPC listen port (emulator convention); must be a valid port and **distinct** from the gRPC / REST / HTTP / AWS-connector ports |
| `AdvertisedEndpoint`         | `CONNECTORS_GCP_ADVERTISED_ENDPOINT`           | `""`                | `host:port` shown in the dashboard `PUBSUB_EMULATOR_HOST` hint. **Cosmetic** — does not change listen behavior                  |
| `MaxMessageBytes`            | `CONNECTORS_GCP_MAX_MESSAGE_BYTES`             | `10485760` (10 MiB) | Max total message size; also sizes the gRPC frame. Must be > 0                                                                  |
| `DefaultAckDeadlineSeconds`  | `CONNECTORS_GCP_DEFAULT_ACK_DEADLINE_SECONDS`  | `10`                | Default ack deadline; must be **10..600**                                                                                       |
| `MaxOutstandingMessages`     | `CONNECTORS_GCP_MAX_OUTSTANDING_MESSAGES`      | `1000`              | Per-stream flow-control ceiling for clients that request unlimited. Must be > 0                                                 |
| `MaxInflightPerSubscription` | `CONNECTORS_GCP_MAX_INFLIGHT_PER_SUBSCRIPTION` | `20000`             | Hard cap on leased (un-acked) messages per subscription. Must be > 0                                                            |
| `MaxConcurrentPolls`         | `CONNECTORS_GCP_MAX_CONCURRENT_POLLS`          | `1024`              | Poller slot budget. Must be > 0                                                                                                 |
| `DeliveryShards`             | `CONNECTORS_GCP_DELIVERY_SHARDS`               | `16`                | Size of the striped delivery-worker pool (fan-out concurrency). Must be **1..256**                                              |
| `MaxAckExtensionSeconds`     | `CONNECTORS_GCP_MAX_ACK_EXTENSION_SECONDS`     | `600`               | Ack-deadline keep-alive budget for the ordered head. `0` disables the keep-alive (expiry → redeliver); otherwise **10..3600**   |
| `StreamCloseSeconds`         | `CONNECTORS_GCP_STREAM_CLOSE_SECONDS`          | `1800`              | Periodic StreamingPull close interval (forces SDK reconnect; bounds per-stream lifetime). Must be > 0                           |
| `MaxSeekReplay`              | `CONNECTORS_GCP_MAX_SEEK_REPLAY`               | `1000000`           | Max messages replayed by a single `Seek` (hits cap → WARN, no silent loss). Must be > 0                                         |
| `EnableReflection`           | `CONNECTORS_GCP_ENABLE_REFLECTION`             | `false`             | Register gRPC server reflection (debugging)                                                                                     |

### Validation [#validation]

Validation returns nil when the connector is disabled. Otherwise the `Port` must be a valid port and
distinct from the gRPC / REST / HTTP / AWS-connector ports; `DefaultAckDeadlineSeconds` must be
**10..600**; `DeliveryShards` must be **1..256**; `MaxAckExtensionSeconds` must be **`0`** (disables
the ordered-head keep-alive) **or 10..3600**; and the six numeric caps (`MaxMessageBytes`,
`MaxOutstandingMessages`, `MaxInflightPerSubscription`, `MaxConcurrentPolls`, `StreamCloseSeconds`,
`MaxSeekReplay`) must be **> 0**.

## DoS guards (always active, even in no-auth emulator mode) [#dos-guards-always-active-even-in-no-auth-emulator-mode]

Even though the connector has no authentication, these guards remain on and cannot be disabled:

* `MaxMessageBytes` — gRPC body cap.
* `MaxInflightPerSubscription` — leased-message ceiling per subscription.
* `MaxConcurrentPolls` — poller slot budget.
* `MaxSeekReplay` — replay ceiling for a single `Seek`.
* push delivery backoff — bounds retry pressure on push endpoints.

<Callout type="warn">
  Do **not** expose port 8085 to untrusted networks — there is no auth or TLS. See
  [Connections & Observability](/connectors/gcp-pub-sub/reference/connections-endpoint) and
  [Connectivity & Emulator Mode](/connectors/gcp-pub-sub/how-to/connectivity-and-emulator-mode).
</Callout>

## Related [#related]

<Cards>
  <Card title="Configuration" href="/connectors/gcp-pub-sub/concepts/configuration" description="The prose walkthrough of every CONNECTORS_GCP_* config field." />

  <Card title="Capabilities" href="/connectors/gcp-pub-sub/reference/capabilities" description="What the connector supports, accepts-and-ignores, or rejects." />

  <Card title="Error Codes" href="/connectors/gcp-pub-sub/reference/error-codes" description="What a limit violation returns on the wire." />

  <Card title="Channel Mapping" href="/connectors/gcp-pub-sub/reference/channel-mapping" description="The resource-id-to-channel grammar these rules govern." />
</Cards>