What causes "TDengine query session not found: {session_id}" in t8y2/dbx?

Re-run the original query to obtain a fresh session_id and re-fetch from page 1

TDengine query session not found: {session_id}

Error message

TDengine query session not found: {session_id}

What it means

fetch_query_page continues a paged query by looking up a server-side cursor stored under the given session_id in an in-process session map. If no such session exists (expired, evicted by expire_query_sessions, never created, or from a different process/restart), it errors. Sessions are held in memory, so they do not survive process restarts or expiry.

Source

Thrown at agents/drivers/tdengine/src/driver.rs:377

            self.query_sessions.insert(session_id, cursor);
        }
        page.execution_time_ms = start.elapsed().as_millis() as i64;
        if may_change_metadata(&options.sql) {
            self.table_cache = None;
        }
        Ok(page)
    }

    pub async fn fetch_query_page(
        &mut self,
        session_id: &str,
        page_size: usize,
        timeout_secs: u64,
        token: &CancellationToken,
    ) -> Result<QueryPageResult> {
        self.expire_query_sessions();
        let Some(mut cursor) = self.query_sessions.remove(session_id) else {
            bail!("TDengine query session not found: {session_id}");
        };
        cursor.last_accessed_at = Instant::now();
        let page_size = normalized_page_size(page_size, 0, cursor.remaining_limit().max(1));
        let mut page = read_cursor_page(&mut cursor, page_size, token, timeout_secs).await?;
        let (has_more, truncated) = cursor.prepare_next_page(token, timeout_secs).await?;
        page.truncated = truncated;
        if has_more {
            page.session_id = Some(session_id.to_string());
            page.has_more = true;
            self.query_sessions.insert(session_id.to_string(), cursor);
        }
        Ok(page)
    }

    pub fn close_query_session(&mut self, session_id: &str) -> bool {
        self.query_sessions.remove(session_id).is_some()
    }

View on GitHub (pinned to c0390bff16)

Solutions

Re-run the original query to obtain a fresh session_id and re-fetch from page 1
Fetch pages promptly before the session TTL expires
Ensure all page requests for one query go to the same agent instance (sticky routing) and avoid restarts mid-pagination

Example fix

// before
let page = driver.fetch_query_page(&stale_session_id, page_size, timeout, &token).await?;
// after
let page = match driver.fetch_query_page(&session_id, page_size, timeout, &token).await {
    Ok(p) => p,
    Err(_) if session_gone => { let s = driver.execute_query_page(&sql, ...).await?; /* use new session */ }
    Err(e) => return Err(e),
};

Defensive patterns

Strategy: retry

Validate before calling

// track session freshness client-side
if session.last_used.elapsed() > SESSION_TTL / 2 { reissue_session(); }

Try / catch

match driver.fetch_query_page(&session_id, size, timeout, &token).await {
    Err(e) if e.to_string().contains("session not found") => restart_query_from_page_one(),
    other => other,
}

Prevention

Re-issue sessions after agent restarts
Use sticky routing for paged requests
Fetch pages faster than the session TTL

When it happens

Trigger: Requesting the next page with a session_id that was never returned by a prior query, reusing a session after its TTL expired (expire_query_sessions removed it), or after the agent process restarted.

Common situations: Long pauses between page fetches exceeding the session TTL, load-balanced deployments where page requests hit a different agent instance, or app restarts while a client holds a paging token.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/5fb6711e858fd484. Report an issue: GitHub.