#Hangs at "⠴ Checking for index or schema changes..."

18 messages · Page 1 of 1 (latest)

sage loom
#

I am using a starter template. I've cleaned out most of the old code. Only have these schema files as far as entities go.

import { defineEntSchema, getEntDefinitions } from "convex-ents"
import { users } from "./schema/users"
import { notifications } from "./schema/notifications"

const schema = defineEntSchema(
{
users,
notifications,
},
{ schemaValidation: true },
)

export default schema

export const entDefinitions = getEntDefinitions(schema)

import { defineEnt } from "convex-ents"
import { v } from "convex/values"

// Minimal user entity used across the app
export const users = defineEnt({
username: v.optional(v.string()),
pictureUrl: v.optional(v.string()),
})
.field("email", v.string(), { unique: true })
// Clerk token identifier (e.g. issuer|subject)
.field("tokenIdentifier", v.string(), { unique: true })
.edges("members", { ref: true, deletion: "soft" })
.deletion("soft")

import { defineEnt } from "convex-ents"
import { v } from "convex/values"

export const notifications = defineEnt({
type: v.string(),
isRead: v.boolean(),
readAt: v.optional(v.number()),
dataJson: v.string(),
})
.field("userId", v.string())
.index("by_user", ["userId"])

Yet when I run CONVEX_VERBOSE=1 npx convex dev it gets to "[verbose] 2025-08-08T23:39:36.125Z Preparing convex/utils.ts" and then hangs.

orchid starBOT
#

Hi @sage loom. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

Based on the information in the knowledge sources, when Convex hangs at "⠴ Checking for index or schema changes...", it is often related to network issues or problems connecting to the Convex cloud service. This can be caused by local network problems, VPNs, or temporary service issues on Convex's side. Several users have reported similar symptoms, and the recommended steps are:

  1. Check your network connection: Make sure you are not behind a restrictive firewall, VPN, or proxy that could block outgoing connections to Convex. Try switching networks or disabling VPNs if you are using any.

  2. Run network diagnostics: Use the command below to help diagnose connectivity issues:

    npx convex network-test

    This will check DNS and TCP connectivity to your deployment. If you see failures (especially on TCP connect), it indicates a network-level problem between your machine and Convex's servers. In one case, a user in Indonesia experienced persistent TCP failures, which pointed to a local or regional network issue rather than a problem with Convex itself. If you see similar errors, try from a different network or location if possible Network issue: can't connect with Convex.

  3. Verbose logging: You are already using CONVEX_VERBOSE=1 npx convex dev, which is good for debugging. You can also try the -v flag for additional verbosity, as suggested by support staff stuck on npx convex deploy.

#

  1. Service status: Sometimes, Convex itself may have temporary outages or backend issues. These are rare, but if you suspect this, you can check with the Convex team or their status channels. In one case, a backend failover caused temporary issues for multiple users, which resolved after a short time Unable to connect to convex.

  2. Schema issues: While your schema looks reasonable, if there is a schema error, Convex should report it. However, if the process hangs before reporting an error, it is more likely a network or connectivity issue rather than a schema problem.

Summary:
The most likely cause for hanging at "Checking for index or schema changes..." is a network connectivity issue between your machine and Convex's servers. Run npx convex network-test to diagnose, and try from a different network if possible. If the problem persists and network tests pass, consider reaching out to Convex support with your verbose logs for further assistance.

If you need more detailed troubleshooting, please provide the output of npx convex network-test and any additional error messages you see.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@sage loom Kapa.ai is still learning and improving, please let me know how I did by reacting below.

sage loom
#

@orchid star Network test returned fine: npx convex network-test

"✔ Network test passed."

When I opened the base starter kit it easily deployed all of the boilerplate schemas to the db. I erased all of them, ran "rm -rf .convex"

When I add the -v flag I see that we get this after the "Prepareing convex/utils.ts"

Convex's runtime modules: [
'functions.js',
'schema/notifications.js',
'_deps/BU4OVURY.js',
'schema/users.js',
'_deps/YKRUR7G4.js',
'_deps/YHQTD3EE.js',
'types.js',
'utils.js',
'_deps/DHT6NSOA.js'
]

then it hangs.

orchid starBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Thank you for the detailed follow-up. Based on the knowledge sources provided, here’s what can be determined:

  • Network issues are a common cause of hanging at the "Checking for index or schema changes..." step, but since your npx convex network-test passes and the starter kit works, this is likely not the issue in your case.
  • Verbose output showing Convex's runtime modules being prepared, then hanging, is not directly addressed in the knowledge sources. There are no explicit reports of this exact hang after module preparation, especially when using custom schemas with convex-ents.
  • Schema or code issues: The knowledge sources do mention that certain schema errors (like circular imports or invalid exports) can cause errors or hangs, but these are typically surfaced as error messages, not silent hangs. There is no mention of hangs specifically related to using convex-ents or after deleting the .convex directory.

What is covered in the knowledge sources:

  • If you see a hang or no progress after "Preparing..." or "bundling modules...", sometimes simply restarting your environment or reinstalling dependencies can resolve transient issues, as one user found after a restart, though the root cause was unclear Stuck at "bundling modules for convex's runtime.
  • If you have recently deleted .convex or made significant changes, ensure your environment is clean and dependencies are up to date.
  • There is no explicit documentation or support thread in the provided sources that addresses a hang at this exact step with the use of convex-ents or after schema changes.
#

Summary:
I'm sorry, but the knowledge sources do not contain enough information to confidently diagnose or resolve a hang at the "Preparing convex/utils.ts" or after listing runtime modules, especially in the context of using convex-ents and after deleting .convex. If the starter kit works but your custom schema does not, it may be related to your code or a compatibility issue with convex-ents, but this is not confirmed in the sources.

Next steps:

  • Try reverting to a minimal schema and add entities back one by one to isolate the issue.
  • Ensure all dependencies are up to date and compatible.
  • If the problem persists, consider reaching out to Convex support or the community with your verbose logs, as this specific scenario is not covered in the current knowledge sources.

If you have more details or error messages, please share them, and I can check again for any relevant information.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@sage loom Kapa.ai is still learning and improving, please let me know how I did by reacting below.

sage loom
orchid starBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

The error message you’re seeing:

✖ Error: Unable to run schema validation on <https://A-B-C.convex.cloud>
✖ Error fetching POST  <https://A-B-C.convex.cloud/api/prepare_schema> 408 Request Timeout
Failed due to network error, retrying in 759.97ms...

indicates that your local Convex CLI is unable to reach the Convex cloud service to perform schema validation, resulting in a 408 Request Timeout. This is a network-level error, not a schema or code error.

What the knowledge sources say:

  • This type of error is most often caused by local network issues, VPNs, proxies, or restrictive firewalls. Even if the network-test passes, transient or intermittent network issues can still cause timeouts during actual schema validation requests. Users have reported similar issues that were resolved by switching networks, disabling VPNs, or simply waiting and trying again later. Sometimes, these issues are also caused by temporary service interruptions on Convex’s side, but this is rare and usually resolved quickly Network issue: can't connect with Convex, Unable to run schema Validation.

  • If you are on a VPN, try disconnecting and running the command again. If you are on a mobile hotspot or a network with unusual routing (such as IPv6 issues), try switching to a different network or disabling IPv6, as some users have found this resolves the issue convex dev can't reach server.

#
  • If the issue persists across different networks and you are not using a VPN or proxy, it could be a temporary issue with Convex’s backend. In such cases, waiting and retrying later has resolved the problem for some users Unable to connect to convex.

Summary:
This is a network timeout issue between your machine and Convex’s cloud service. Try switching networks, disabling VPNs, or waiting and retrying. If the problem continues, reach out to Convex support with your logs and details about your network environment.

If you have already tried these steps and the issue persists, please provide more details about your network setup, and any recent changes, or try from a different location to further isolate the cause.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@sage loom Kapa.ai is still learning and improving, please let me know how I did by reacting below.

sage loom
#

@orchid star i don't want my queries/mutations/schemas floating around in the /convex directory among config files and the like. I'd like to nest them under /conves/api. Is there a way to path alias that with a convex config?

orchid starBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Based on the knowledge sources, Convex does not currently support customizing the location of your functions (queries, mutations, etc.) to a subdirectory like /convex/api via a path alias or configuration option. The only supported customization is changing the root convex/ folder itself (for example, to src/convex/) using the functions field in your convex.json:

{
  "functions": "src/convex/"
}

However, you cannot specify a subfolder within the convex/ directory (such as convex/api/) as the root for your API functions while keeping config files at the top level. All Convex functions must live directly inside the configured convex/ directory or its subdirectories, and there is no way to alias or remap the API object to a nested folder like convex/api while keeping config files separate. This limitation is confirmed by Convex staff in community discussions:

No, there’s no customization of your convex folder structure. On the frontend you can do
const myApi = api.functions
but you can’t change where Convex looks for functions beyond the root folder itself
Discord support thread: Different functions and root folders?

So, while you can organize your functions in subfolders within convex/, you cannot move all API functions under a single subdirectory like convex/api and have Convex recognize that as the root for API generation. All config files and functions must coexist within the same root directory.

If you want to keep things organized, you can use subfolders within convex/ (e.g., convex/users/, convex/posts/), but not a separate root for API functions only.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: