Troubleshooting guide and feature toggles reference for 2501
Common issues and solutions for 2501 deployments.
Common Issues
Registry Authentication Failed
Registry authentication is handled by the CLI on every deploy, so there is no credential helper or docker login to fix. If a deploy reports an image pull or authentication failure, confirm the pull-only registry key from 2501 was supplied at install (or that the node’s AWS credentials resolve), then re-run the deploy to fetch a fresh token. Run 2501 infra config to inspect the effective registry configuration.
Database Connection Failed
# Test connectionpsql "postgresql://<user>:<password>@<host>:5432/2501"# Check DATABASE_URL format# postgresql://<user>:<password>@<host>:<port>/<database>?schema=public
Services Not Starting
# View logsdocker service logs -f 2501_enginedocker service logs -f 2501_command-center# Check resourcesdocker stats
Migration Failed
# Check database is accessible# Check DATABASE_URL and DIRECT_URL are correct# Retry deployment2501 infra deploy
Viewing Logs
docker service logs -f 2501_enginedocker service logs -f 2501_command-center# All services statusdocker stack services 2501
Health Checks
curl http://localhost:1337/health # Enginecurl http://localhost:3000/health # Command Center
Reset Everything
This will delete all data. Only use this for development/testing environments.
# Stop and remove2501 infra deploy --remove# Remove volumes (WARNING: deletes data)docker volume rm $(docker volume ls -q | grep 2501)# Redeploy2501 infra deploy
Upgrading
There is no separate update command. Run an interactive 2501 infra deploy: it lists published releases newest-first, and when you pick a version it self-updates its own binary to match (checksum-verified, then re-executed) before deploying. This keeps the CLI in lockstep with the deployed platform version.To refresh only the CLI binary, re-run the installer. It is idempotent and never touches an existing workspace.
Feature toggles
Toggle reference and CLI moved to its own page — see Feature Toggles.
Support
For issues or questions:
Check logs and health endpoints
Verify configuration against this guide
Contact 2501.ai support
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"2501.ai","colors":{"primary":"#121212","light":"#FAFAFA","dark":"#121212"},"logo":{"light":"https://mintcdn.com/2501/gMl_w8qww9Zl47hO/logo/light.png?fit=max\u0026auto=format\u0026n=gMl_w8qww9Zl47hO\u0026q=85\u0026s=eeeb37b3ca386a00dde53b3e6235adce","dark":"https://mintcdn.com/2501/gMl_w8qww9Zl47hO/logo/dark.png?fit=max\u0026auto=format\u0026n=gMl_w8qww9Zl47hO\u0026q=85\u0026s=4d0ac2514d479eb43fe361193d12c495","href":"/0.7/getting-started/welcome"},"favicon":"https://mintcdn.com/2501/gMl_w8qww9Zl47hO/favicon.png?fit=max\u0026auto=format\u0026n=gMl_w8qww9Zl47hO\u0026q=85\u0026s=884be98d09b5672f470de49ac6430f22","appearance":{"default":"light"},"background":{"color":{"light":"#FAFAFA","dark":"#121212"}},"navbar":{"links":[{"href":"mailto:hello@2501.ai","label":"Contact"},{"href":"https://github.com/2501-ai","label":"Github"},{"href":"https://2501.ai/","label":"Website"}]},"footer":{"socials":{"website":"https://www.2501.ai/","github":"https://github.com/2501-ai","linkedin":"https://www.linkedin.com/company/99099126"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"2501","hasAudioNarration":false,"actualSubdomain":"2501","customDomains":["docs.2501.ai"],"gitSource":{"type":"github","owner":"2501-ai","repo":"2501","deployBranch":"main","contentDirectory":"apps/public-docs","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6afc5666837a82b451e76d01","clientVersion":"0.0.4167","searchFilterCounts":[{"language":"default","tag":"Reference","count":1101},{"language":"default","tag":"API","count":603},{"language":"default","tag":"Configure","count":320},{"language":"default","tag":"Guides","count":210},{"language":"default","tag":"Docs","count":205},{"language":"default","tag":"Benchmark","count":185},{"language":"default","tag":"Deploy","count":138},{"language":"default","tag":"Agents","count":138},{"language":"default","tag":"Integration","count":121},{"language":"default","tag":"Concepts","count":121}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"0.7/deployment/troubleshooting","slug":"/0.7/deployment/troubleshooting","pageMetadata":{"title":"Troubleshooting","description":"Troubleshooting guide and feature toggles reference for 2501","href":"/0.7/deployment/troubleshooting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Troubleshooting guide and feature toggles reference for 2501\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,hr:`hr`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Common issues and solutions for 2501 deployments.`}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`common-issues`,children:`Common Issues`}),`\n`,_jsx(Heading,{level:`3`,id:`registry-authentication-failed`,children:`Registry Authentication Failed`}),`\n`,_jsxs(_components.p,{children:[`Registry authentication is handled by the CLI on every deploy, so there is no credential helper or `,_jsx(_components.code,{children:`docker login`}),` to fix. If a deploy reports an image pull or authentication failure, confirm the pull-only registry key from 2501 was supplied at install (or that the node’s AWS credentials resolve), then re-run the deploy to fetch a fresh token. Run `,_jsx(_components.code,{children:`2501 infra config`}),` to inspect the effective registry configuration.`]}),`\n`,_jsx(Heading,{level:`3`,id:`database-connection-failed`,children:`Database Connection Failed`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Test connection`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`psql`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"postgresql://\u003cuser>:\u003cpassword>@\u003chost>:5432/2501\"`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check DATABASE_URL format`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# postgresql://\u003cuser>:\u003cpassword>@\u003chost>:\u003cport>/\u003cdatabase>?schema=public`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`services-not-starting`,children:`Services Not Starting`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# View logs`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` service`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 2501_engine`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` service`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 2501_command-center`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check resources`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` stats`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`migration-failed`,children:`Migration Failed`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check database is accessible`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Check DATABASE_URL and DIRECT_URL are correct`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Retry deployment`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`2501`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` infra`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` deploy`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`viewing-logs`,children:`Viewing Logs`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` service`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 2501_engine`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` service`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 2501_command-center`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# All services status`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` stack`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` services`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 2501`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`health-checks`,children:`Health Checks`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` http://localhost:1337/health`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Engine`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` http://localhost:3000/health`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Command Center`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`reset-everything`,children:`Reset Everything`}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`This will delete all data. Only use this for development/testing environments.`})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Stop and remove`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`2501`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` infra`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` deploy`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --remove`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Remove volumes (WARNING: deletes data)`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` volume`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` rm`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` $(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` volume`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ls`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -q`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` grep`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 2501`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Redeploy`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`2501`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` infra`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` deploy`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`upgrading`,children:`Upgrading`}),`\n`,_jsxs(_components.p,{children:[`There is no separate update command. Run an interactive `,_jsx(_components.code,{children:`2501 infra deploy`}),`: it lists published releases newest-first, and when you pick a version it self-updates its own binary to match (checksum-verified, then re-executed) before deploying. This keeps the CLI in lockstep with the deployed platform version.`]}),`\n`,_jsx(_components.p,{children:`To refresh only the CLI binary, re-run the installer. It is idempotent and never touches an existing workspace.`}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`feature-toggles`,children:`Feature toggles`}),`\n`,_jsxs(_components.p,{children:[`Toggle reference and CLI moved to its own page — see `,_jsx(_components.a,{href:`/0.7/deployment/feature-toggles`,children:`Feature Toggles`}),`.`]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`support`,children:`Support`}),`\n`,_jsx(_components.p,{children:`For issues or questions:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsx(_components.li,{children:`Check logs and health endpoints`}),`\n`,_jsx(_components.li,{children:`Verify configuration against this guide`}),`\n`,_jsx(_components.li,{children:`Contact 2501.ai support`}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Troubleshooting","description":"Troubleshooting guide and feature toggles reference for 2501","href":"/0.7/deployment/troubleshooting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Common Issues","slug":"common-issues","depth":2,"children":[{"title":"Registry Authentication Failed","slug":"registry-authentication-failed","depth":3,"children":[]},{"title":"Database Connection Failed","slug":"database-connection-failed","depth":3,"children":[]},{"title":"Services Not Starting","slug":"services-not-starting","depth":3,"children":[]},{"title":"Migration Failed","slug":"migration-failed","depth":3,"children":[]}]},{"title":"Viewing Logs","slug":"viewing-logs","depth":2,"children":[]},{"title":"Health Checks","slug":"health-checks","depth":2,"children":[]},{"title":"Reset Everything","slug":"reset-everything","depth":2,"children":[]},{"title":"Upgrading","slug":"upgrading","depth":2,"children":[]},{"title":"Feature toggles","slug":"feature-toggles","depth":2,"children":[]},{"title":"Support","slug":"support","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"2501","siteName":"2501.ai","title":"Troubleshooting - 2501.ai","navMaps":{"firstHrefInVersion":{"0.20":{"href":"/0.20/deployment/troubleshooting","matchLevel":1},"0.19":{"href":"/0.19/deployment/troubleshooting","matchLevel":1},"0.18":{"href":"/0.18/deployment/troubleshooting","matchLevel":1},"0.17":{"href":"/0.17/deployment/troubleshooting","matchLevel":1},"0.16":{"href":"/0.16/deployment/troubleshooting","matchLevel":1},"0.15":{"href":"/0.15/deployment/troubleshooting","matchLevel":1},"0.14":{"href":"/0.14/deployment/troubleshooting","matchLevel":1},"0.13":{"href":"/0.13/deployment/troubleshooting","matchLevel":1},"0.12":{"href":"/0.12/deployment/troubleshooting","matchLevel":1},"0.11":{"href":"/0.11/deployment/troubleshooting","matchLevel":1},"0.10":{"href":"/0.10/deployment/troubleshooting","matchLevel":1},"0.9":{"href":"/0.9/deployment/troubleshooting","matchLevel":1},"0.8":{"href":"/0.8/deployment/troubleshooting","matchLevel":1},"0.7":{"href":"/0.7/deployment/troubleshooting","matchLevel":0},"0.4":{"href":"/0.4/deployment/troubleshooting","matchLevel":1},"0.3.0":{"href":"/0.3.0/deployment/troubleshooting","matchLevel":1},"0.2.6":{"href":"/0.2.6/deployment/troubleshooting","matchLevel":1}},"firstHrefInLanguage":{}},"lastModified":"2026-06-16T09:19:38.206Z","originalFileLocation":"0.7/deployment/troubleshooting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Troubleshooting guide and feature toggles reference for 2501\">\u003cmeta data-mint-head name=\"application-name\" content=\"2501.ai\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Troubleshooting - 2501.ai\">\u003cmeta data-mint-head property=\"og:description\" content=\"Troubleshooting guide and feature toggles reference for 2501\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"2501.ai\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.2501.ai/0.7/deployment/troubleshooting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://2501.mintlify.site/_mintlify/api/og/v2?division=Deploy\u0026amp;title=Troubleshooting\u0026amp;description=Troubleshooting+guide+and+feature+toggles+reference+for+2501\u0026amp;theme=f1d0d4ed6e37b0ff35bfc2cb\u0026amp;signature=69d61bff1df5cf0474b57023265f15214fa947b1639ddb61d8e368a6d3c0cb3f\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Troubleshooting - 2501.ai\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Troubleshooting guide and feature toggles reference for 2501\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://2501.mintlify.site/_mintlify/api/og/v2?division=Deploy\u0026amp;title=Troubleshooting\u0026amp;description=Troubleshooting+guide+and+feature+toggles+reference+for+2501\u0026amp;theme=f1d0d4ed6e37b0ff35bfc2cb\u0026amp;signature=69d61bff1df5cf0474b57023265f15214fa947b1639ddb61d8e368a6d3c0cb3f\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/2501/ur2ley-wQyHAsGwc/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"2501.ai\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#121212\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.2501.ai/0.7/deployment/troubleshooting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/0.7/deployment/troubleshooting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.2501.ai/#organization\",\"name\":\"2501.ai\",\"url\":\"https://docs.2501.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/2501/gMl_w8qww9Zl47hO/logo/light.png?fit=max\u0026auto=format\u0026n=gMl_w8qww9Zl47hO\u0026q=85\u0026s=eeeb37b3ca386a00dde53b3e6235adce\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.2501.ai#website\",\"name\":\"2501.ai\",\"url\":\"https://docs.2501.ai\",\"publisher\":{\"@id\":\"https://docs.2501.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.2501.ai/0.7/deployment/troubleshooting#webpage\",\"url\":\"https://docs.2501.ai/0.7/deployment/troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Troubleshooting guide and feature toggles reference for 2501\",\"dateModified\":\"2026-06-16T09:19:38.206Z\",\"isPartOf\":{\"@id\":\"https://docs.2501.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.2501.ai/0.7/deployment/troubleshooting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.2501.ai/0.7/deployment/troubleshooting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Deploy\",\"item\":\"https://docs.2501.ai/0.7/deployment/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Troubleshooting\",\"item\":\"https://docs.2501.ai/0.7/deployment/troubleshooting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.2501.ai/0.7/deployment/troubleshooting#article\",\"headline\":\"Troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Troubleshooting guide and feature toggles reference for 2501\",\"url\":\"https://docs.2501.ai/0.7/deployment/troubleshooting\",\"mainEntityOfPage\":{\"@id\":\"https://docs.2501.ai/0.7/deployment/troubleshooting#webpage\"},\"dateModified\":\"2026-06-16T09:19:38.206Z\",\"publisher\":{\"@id\":\"https://docs.2501.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.2501.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"2501.ai\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"2501.ai\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/0.7/deployment/troubleshooting.md","siteName":"2501.ai","nav":{"global":null,"versions":[{"version":"0.20","pages":[{"title":"0.20","href":"/0.20/deployment/troubleshooting"}]},{"version":"0.19","pages":[{"title":"0.19","href":"/0.19/deployment/troubleshooting"}]},{"version":"0.18","pages":[{"title":"0.18","href":"/0.18/deployment/troubleshooting"}]},{"version":"0.17","pages":[{"title":"0.17","href":"/0.17/deployment/troubleshooting"}]},{"version":"0.16","pages":[{"title":"0.16","href":"/0.16/deployment/troubleshooting"}]},{"version":"0.15","pages":[{"title":"0.15","href":"/0.15/deployment/troubleshooting"}]},{"version":"0.14","pages":[{"title":"0.14","href":"/0.14/deployment/troubleshooting"}]},{"version":"0.13","pages":[{"title":"0.13","href":"/0.13/deployment/troubleshooting"}]},{"version":"0.12","pages":[{"title":"0.12","href":"/0.12/deployment/troubleshooting"}]},{"version":"0.11","pages":[{"title":"0.11","href":"/0.11/deployment/troubleshooting"}]},{"version":"0.10","pages":[{"title":"0.10","href":"/0.10/deployment/troubleshooting"}]},{"version":"0.9","pages":[{"title":"0.9","href":"/0.9/deployment/troubleshooting"}]},{"version":"0.8","pages":[{"title":"0.8","href":"/0.8/deployment/troubleshooting"}]},{"version":"0.7","tabs":[{"tab":"Docs","pages":[{"title":"Docs","href":"/0.7/getting-started/welcome"}]},{"tab":"Reference","groups":[{"group":"CLI","pages":[{"title":"2501 CLI","href":"/0.7/cli/overview"},{"title":"login \u0026 status","href":"/0.7/cli/login-status"},{"title":"resources","href":"/0.7/cli/resources"},{"title":"infra","href":"/0.7/cli/infra"},{"title":"runner","href":"/0.7/cli/runner"},{"title":"chat","href":"/0.7/cli/chat"}]},{"group":"Deploy","pages":[{"title":"Overview","href":"/0.7/deployment/overview"},{"title":"Init Command","href":"/0.7/deployment/init-command"},{"title":"Configuration","href":"/0.7/deployment/configuration"},{"title":"Docker Swarm","href":"/0.7/deployment/docker-swarm"},{"title":"Kubernetes","href":"/0.7/deployment/kubernetes"},{"title":"LLM Providers","href":"/0.7/deployment/llm-providers"},{"title":"Users \u0026 Organizations","description":"Manage users, organizations, and tenants in 2501","href":"/0.7/deployment/users-organizations"},{"title":"Troubleshooting","href":"/0.7/deployment/troubleshooting"},{"title":"Feature Toggles","description":"Toggle experimental and optional behaviors on or off","href":"/0.7/deployment/feature-toggles"}]},{"group":"Configure","pages":[{"group":"Agent Behavior","pages":[{"title":"Specialties","href":"/0.7/configure/specialties"},{"title":"Operational Rules","href":"/0.7/configure/operational-rules"},{"title":"Blacklist","href":"/0.7/configure/blacklist"}]},{"title":"Knowledge Base","href":"/0.7/configure/knowledge"},{"group":"Access \u0026 Secrets","pages":[{"title":"Credentials","href":"/0.7/configure/credentials"},{"title":"Plugins","href":"/0.7/configure/plugins"}]},{"group":"Integration","pages":[{"title":"Webhooks","href":"/0.7/configure/webhooks"},{"title":"Configuration as Code","href":"/0.7/configure/configuration-as-code"},{"group":"Resource Reference","pages":[{"title":"Agent","href":"/0.7/configure/resources/agents"},{"title":"Host","href":"/0.7/configure/resources/hosts"},{"title":"Specialty","href":"/0.7/configure/resources/specialties"},{"title":"Operational Rule","href":"/0.7/configure/resources/operational-rules"},{"title":"Credential","href":"/0.7/configure/resources/credentials"},{"title":"Gateway","href":"/0.7/configure/resources/gateways"},{"title":"Blacklist","href":"/0.7/configure/resources/blacklist"}]},{"title":"Import Hosts via CSV","href":"/0.7/configure/import-hosts-csv"}]},{"group":"LLM","pages":[{"title":"Providers","href":"/0.7/configure/providers"},{"title":"Models","href":"/0.7/configure/models"}]},{"title":"Users","href":"/0.7/configure/users"},{"title":"Licensing \u0026 Usage","href":"/0.7/configure/licensing"}]}]},{"tab":"Benchmark","pages":[{"title":"Benchmark","href":"/0.7/benchmark/overview"}]},{"tab":"Guides","pages":[{"title":"Guides","href":"/0.7/configure/prompting"}]}]},{"version":"0.4","pages":[{"title":"0.4","href":"/0.4/deployment/troubleshooting"}]},{"version":"0.3.0","pages":[{"title":"0.3.0","href":"/0.3.0/deployment/troubleshooting"}]},{"version":"0.2.6","pages":[{"title":"0.2.6","href":"/0.2.6/deployment/troubleshooting"}]}]},"basePath":"","title":"Troubleshooting - 2501.ai","buildId":"dpl_9RFrWkXdFTJCytfx6jAofvAaEXr6","deploymentId":"dpl_9RFrWkXdFTJCytfx6jAofvAaEXr6","dynamics":[],"chunks":[]}