We are currently planning a major upgrade of our self-hosted Airbyte instance, migrating from version

0.59.1

to

2.3.0

. We rely heavily on the Declarative CDK and have dozens of custom connectors. Because of this scale, recreating each of them manually from scratch via the Connector Builder UI is completely unfeasible for our team. Initially, we tried the straightforward approach: exporting the YAML manifest from the obsolete version and importing it directly into the new version's Connector Builder. However, this approach throws validation errors and fails to save the draft. Since a simple UI import doesn't work for these legacy manifests, we are looking for suggestions on how to best handle this transition. What is the officially recommended approach to migrate and deploy these legacy YAML manifests into v2.3.0? Any guidance or documentation you could share would be hugely appreciated! Thanks in advance.

Thinking completed I'm sorry, but the knowledge sources do not contain official documentation specifically covering a migration path from Airbyte

0.59.1

to

2.3.0

for dozens of custom Connector Builder connectors. However, I can share what the knowledge sources do reveal about this problem space, along with some important caveats. What the Knowledge Sources Tell Us Why Your Import Fails The validation errors you're seeing are almost certainly a CDK version mismatch. The

version

field in your legacy manifests (from

0.59.1

) references a very old CDK version, while Airbyte

2.3.0

ships with a much newer CDK (major version 7.x). The platform validates that the declared CDK version is compatible. [Forum Post] Known Issue: Fresh Installs Cannot Publish There is also an open GitHub issue confirming that on fresh installs of Airbyte 2.x, the

declarative_manifest_image_version

table only seeds major versions 0–4, while the current CDK is at major 7. This means even if you get your manifests imported, publishing them may return a 500 error until the table is manually updated. This bug still reproduces on platform

2.4.0

as of October 2026. [GitHub Issue] The Workaround for the Publishing Bug A SQL workaround has been documented in the issue thread. You would need to manually update the

declarative_manifest_image_version

table in your Airbyte database:

UPDATE declarative_manifest_image_version
   SET image_version = '7.33.0',
       image_sha = 'sha256:3343cc05b79b9a3c07fa90152bd5348da7154b44f63521857bd2a745883d85cd',
       updated_at = now()
 WHERE major_version = 7;

[GitHub Issue] Approaches Mentioned in the Community 1. API-based deployment: Use the Airbyte configuration API (

POST /v1/connector_builder_projects/publish

or the declarative source definition endpoints) to programmatically create connectors rather than using the UI. This is more scriptable for dozens of connectors. [CI/CD Forum] 2. Terraform: The

airbyte_declarative_source_definition

Terraform resource accepts a raw manifest JSON, which could allow you to script the deployment of all your connectors at once. [Terraform Docs] 3. Manifest version bumping: Before importing, you may need to update the

version

field in each YAML manifest to match the CDK version your new Airbyte instance uses. The new platform automatically sets this field on publish, but legacy manifests with old version declarations will fail validation. [Forum Post] My Honest Assessment The knowledge sources do not provide an officially documented, end-to-end migration guide for this specific scenario (dozens of legacy custom connectors, 0.59.x → 2.x). The gap between these versions is very large (~100 releases), and the community guidance for general upgrades of this magnitude suggests a fresh install is the recommended path. [GitHub Discussion] I would strongly recommend: • Opening a support ticket or posting in the Airbyte Slack / GitHub Discussions with your specific use case, as this is a complex migration that warrants official guidance. • Reviewing the Airbyte breaking changes documentation for the versions between

0.59.1

and

2.3.0

. 👍 0 button 👎 0 button ℹ️ Tip: Mention @kapa.ai in the thread for follow-ups or DM the app for 1-to-1 help.

We’ve spun up a new instance running the latest version of Airbyte, and now we need to move our custom connectors over to this new instance. What’s the best way to go about this?