diff --git a/mint.json b/mint.json index 88a61371..fdf5c280 100644 --- a/mint.json +++ b/mint.json @@ -418,7 +418,13 @@ "group": "Resources", "pages": [ "resources/demo-apps-example-projects", - "resources/local-first-software", + { + "group": "Troubleshooting", + "pages": [ + "resources/troubleshooting", + "resources/troubleshooting/error-codes" + ] + }, { "group": "Usage & Billing", "pages": [ @@ -427,11 +433,11 @@ "resources/usage-and-billing-faq" ] }, - "resources/troubleshooting", "resources/performance-and-limits", "resources/feature-status", "resources/supported-hardware", "resources/faq", + "resources/local-first-software", "resources/release-notes", "resources/roadmap", "resources/blog", diff --git a/resources/troubleshooting.mdx b/resources/troubleshooting.mdx index 21cc1779..17e16471 100644 --- a/resources/troubleshooting.mdx +++ b/resources/troubleshooting.mdx @@ -1,6 +1,7 @@ --- title: "Troubleshooting" description: "Summary of common issues, troubleshooting tools and pointers." +sidebarTitle: "Overview" --- ## Common issues diff --git a/resources/troubleshooting/error-codes.mdx b/resources/troubleshooting/error-codes.mdx new file mode 100644 index 00000000..a8e3a3b8 --- /dev/null +++ b/resources/troubleshooting/error-codes.mdx @@ -0,0 +1,251 @@ +--- +title: "Error Codes Reference" +description: "Complete list of PowerSync error codes with explanations and troubleshooting guidance." +sidebarTitle: "Error Codes" +--- + +This reference documents PowerSync error codes organized by component, with troubleshooting suggestions for developers. Use the search bar to look up specific error codes (e.g., `PSYNC_R0001`). + +# PSYNC_Rxxxx: Sync rules issues + +- **PSYNC_R0001**: + Catch-all sync rules parsing error, if no more specific error is available + +# PSYNC_Sxxxx: Service issues + +- **PSYNC_S0001**: + Internal assertion. + + If you see this error, it might indicate a bug in the service code. + +- **PSYNC_S0102**: + TEARDOWN was not acknowledged. + + This happens when the TEARDOWN argument was not supplied when running + the service teardown command. The TEARDOWN argument is required since + this is a destructive command. + + Run the command with `teardown TEARDOWN` to confirm. + +## PSYNC_S1xxx: Replication issues + +- **PSYNC_S1002**: + Row too large. + + There is a 15MB size limit on every replicated row - rows larger than + this cannot be replicated. + +- **PSYNC_S1003**: + Sync rules have been locked by another process for replication. + + This error is normal in some circumstances: + 1. In some cases, if a process was forcefully terminated, this error may occur for up to a minute. + 2. During rolling deploys, this error may occur until the old process stops replication. + + If the error persists for longer, this may indicate that multiple replication processes are running. + Make sure there is only one replication process apart from rolling deploys. + +- **PSYNC_S1004**: + JSON nested object depth exceeds the limit of 20. + + This may occur if there is very deep nesting in JSON or embedded documents. + +## PSYNC_S11xx: Postgres replication issues + +- **PSYNC_S1101**: + Replication assertion error. + + If you see this error, it might indicate a bug in the service code. + +- **PSYNC_S1103**: + Aborted initial replication. + + This is not an actual error - it is expected when the replication process + is stopped, or if replication is stopped for any other reason. + +- **PSYNC_S1104**: + Explicit cacert is required for `sslmode: verify-ca`. + + Use either verify-full, or specify a certificate with verify-ca. + +- **PSYNC_S1105**: + `database` is required in connection config. + + Specify the database explicitly, or in the `uri` field. + +- **PSYNC_S1106**: + `hostname` is required in connection config. + + Specify the hostname explicitly, or in the `uri` field. + +- **PSYNC_S1107**: + `username` is required in connection config. + + Specify the username explicitly, or in the `uri` field. + +- **PSYNC_S1108**: + `password` is required in connection config. + + Specify the password explicitly, or in the `uri` field. + +- **PSYNC_S1109**: + Invalid database URI. + + Check the URI scheme and format. + +- **PSYNC_S1110**: + Invalid port number. + + Only ports in the range 1024 - 65535 are supported. + +- **PSYNC_S1141**: + Publication does not exist. + + Run: `CREATE PUBLICATION powersync FOR ALL TABLES` on the source database. + +- **PSYNC_S1142**: + Publication does not publish all changes. + + Create a publication using `WITH (publish = "insert, update, delete, truncate")` (the default). + +- **PSYNC_S1143**: + Publication uses publish_via_partition_root. + +## PSYNC_S13xx: MongoDB replication issues + +- **PSYNC_S1301**: + Generic MongoServerError. + +- **PSYNC_S1302**: + Generic MongoNetworkError. + +- **PSYNC_S1303**: + MongoDB internal TLS error. + + If connection to a shared cluster on MongoDB Atlas, this could be an IP Acccess List issue. + Check that the service IP is allowed to connect to the cluster. + +- **PSYNC_S1304**: + MongoDB connection DNS error. + + Check that the hostname is correct. + +- **PSYNC_S1305**: + MongoDB connection timeout. + + Check that the hostname is correct, and that the service IP is allowed to connect to the cluster. + +- **PSYNC_S1306**: + MongoDB authentication error. + + Check the username and password. + +- **PSYNC_S1307**: + MongoDB authorization error. + + Check that the user has the required priviledges. + +- **PSYNC_S1341**: + Sharded MongoDB Clusters are not supported yet. + +- **PSYNC_S1342**: + Standalone MongoDB instances are not supported - use a replicaset. + +- **PSYNC_S1343**: + PostImages not enabled on a source collection. + + Use `post_images: auto_configure` to configure post images automatically, or enable manually: + + ``` + db.runCommand({ + collMod: 'collection-name', + changeStreamPreAndPostImages: { enabled: true } + }); + ``` + +## PSYNC_S14xx: MongoDB storage replication issues + +- **PSYNC_S1402**: + Max transaction tries exceeded. + +## PSYNC_S2xxx: Service API + +- **PSYNC_S2001**: + Generic internal server error (HTTP 500). + + See the error details for more info. + +- **PSYNC_S2002**: + Route not found (HTTP 404). + +- **PSYNC_S2003**: + 503 service unavailable due to restart. + + Wait a while then retry the request. + +## PSYNC_S21xx: Auth errors originating on the client. + +This does not include auth configuration errors on the service. + +- **PSYNC_S2101**: + Generic authentication error. + +## PSYNC_S22xx: Auth integration errors + +- **PSYNC_S2202**: + IPv6 support is not enabled for the JWKS URI. + + Use an endpoint that supports IPv4. + +- **PSYNC_S2203**: + IPs in this range are not supported. + + Make sure to use a publically-accessible JWKS URI. + +## PSYNC_S23xx: Sync API errors + +- **PSYNC_S2302**: + No sync rules available. + + This error may happen if: + 1. Sync rules have not been deployed. + 2. Sync rules have been deployed, but is still busy processing. + + View the replicator logs to see if the sync rules are being processed. + +- **PSYNC_S2304**: + Maximum active concurrent connections limit has been reached. + +## PSYNC_S23xx: Sync API errors - MongoDB Storage + +- **PSYNC_S2401**: + Could not get clusterTime. + +## PSYNC_S31xx: Auth configuration issues + +- **PSYNC_S3102**: + Invalid jwks_uri. + +- **PSYNC_S3103**: + Only http(s) is supported for jwks_uri. + +## PSYNC_S32xx: Replication configuration issue. + +- **PSYNC_S3201**: + Failed to validate module configuration. + +## PSYNC_S4000: Management / Dev APIs + +- **PSYNC_S4001**: + Internal assertion error. + + This error may indicate a bug in the service code. + +- **PSYNC_S4104**: + No active sync rules. + +- **PSYNC_S4105**: + Sync rules API disabled. + + When a sync rules file is configured, the dynamic sync rules API is disabled. +