{"record":{"id":"f1f7d2d675a65aeb","repo":"transact-rs/sqlx","slug":"this-functionality-requires-a-tokio-context","errorCode":null,"errorMessage":"this functionality requires a Tokio context","messagePattern":"this functionality requires a Tokio context","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"sqlx-core/src/rt/mod.rs","lineNumber":166,"sourceCode":"    cfg_if! {\n        if #[cfg(feature = \"_rt-async-io\")] {\n            async_io::block_on(f)\n        } else if #[cfg(feature = \"_rt-tokio\")] {\n            tokio::runtime::Builder::new_current_thread()\n                .enable_all()\n                .build()\n                .expect(\"failed to start Tokio runtime\")\n                .block_on(f)\n        } else {\n            missing_rt(f)\n        }\n    }\n}\n\n#[track_caller]\npub const fn missing_rt<T>(_unused: T) -> ! {\n    if cfg!(feature = \"_rt-tokio\") {\n        panic!(\"this functionality requires a Tokio context\")\n    }\n\n    panic!(\"one of the `runtime` features of SQLx must be enabled\")\n}\n\nimpl<T: Send + 'static> Future for JoinHandle<T> {\n    type Output = T;\n\n    #[track_caller]\n    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {\n        match &mut *self {\n            #[cfg(feature = \"_rt-async-std\")]\n            Self::AsyncStd(handle) => Pin::new(handle).poll(cx),\n\n            #[cfg(feature = \"_rt-async-task\")]\n            Self::AsyncTask(task) => Pin::new(task)\n                .as_pin_mut()\n                .expect(\"BUG: task taken\")","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/transact-rs/sqlx/blob/03af8bcc5711a1935580a54bea249c219a0c217d/sqlx-core/src/rt/mod.rs#L148-L184","documentation":"missing_rt() in sqlx-core/src/rt/mod.rs is sqlx's guard for runtime-abstract APIs. When the `_rt-tokio` feature IS enabled but the API is called outside any active Tokio runtime/context, sqlx panics with 'this functionality requires a Tokio context' (the second panic branch, 'one of the runtime features...' only fires when no runtime feature is compiled in). Many sqlx operations (pool creation, queries, timers) spawn on the async runtime and cannot run without one.","triggerScenarios":"Calling `PgPool::connect`, `Pool::acquire`, `query.fetch...` etc. from code not running inside `#[tokio::main]`/`tokio::runtime::Runtime::block_on` — e.g. from a synchronous main, a blocking thread, a C FFI callback, or tests without the `#[tokio::test]` attribute.","commonSituations":"Rust binaries with plain `fn main()` calling sqlx directly; integration tests missing tokio attributes; embedding sqlx in a non-Tokio app (async-std, smol) while only the tokio feature is enabled.","solutions":["Wrap the entry point in a Tokio runtime: `#[tokio::main] async fn main()` or build one manually with `tokio::runtime::Runtime::new()?.block_on(...)`.","Annotate async tests with `#[tokio::test]` instead of `#[test]`.","If calling from sync code, use `SomePool::connect_lazy` plus a runtime-owned handle, or move DB work onto a Tokio worker via `runtime.spawn(...)`.","If your app uses a non-Tokio runtime, switch the sqlx feature to a matching one — but note current sqlx effectively requires Tokio for runtime-dependent APIs."],"exampleFix":"// before\nfn main() {\n    let pool = PgPool::connect(\"postgres://...\"); // panic: no Tokio context\n}\n\n// after\n#[tokio::main]\nasync fn main() {\n    let pool = PgPool::connect(\"postgres://...\").await.unwrap();\n}","handlingStrategy":"validation","validationCode":"// Ensure a Tokio context exists before DB work:\nassert!(\n    tokio::runtime::Handle::try_current().is_ok(),\n    \"sqlx calls require a Tokio runtime context\"\n);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use #[tokio::main] and #[tokio::test] on every entry point and async test","Never call async sqlx APIs from sync code without block_on","Keep DB access behind async functions that are only awaited within the runtime"],"tags":["async","tokio","runtime","sqlx"],"backgroundTag":"missing-async-runtime-context","analyzedSha":"03af8bcc5711a1935580a54bea249c219a0c217d","analyzedAt":"2026-09-03T15:01:28.752Z","contentChangedAt":"2026-09-03T15:01:28.752Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}