Skip to main content

Integration limitations and troubleshooting

This page collects the limitations and the troubleshooting steps for the two Notebook Engine integrations:

Read the limitations for an integration before you rely on it for work you can't repeat. Several of them describe permanent data loss: H2O Drive keeps no version history and no trash, and the assistant applies a set of changes one operation at a time rather than all or nothing.

Both integrations depend on the image your engine runs, and neither works on a shared engine. For those requirements, see H2O Drive integration prerequisites and Enterprise h2oGPTe assistant prerequisites.

H2O Drive limitations​

The following limitations apply when you work with H2O Drive:

  • Where you edit a notebook depends on how you opened it. Double-clicking a notebook inside an H2O Drive folder copies it to the local workspace, and you edit the copy, so your changes reach H2O Drive only when you save to H2O Drive again. A notebook that is open directly on H2O Drive is edited in place, and every save, including autosave, writes to H2O Drive.
  • Save active notebook to H2O Drive writes to the top level. For a notebook in the local workspace, the action writes to the top level of your H2O Drive, so you can't use it to save into an H2O Drive folder. A notebook that is open directly on H2O Drive is the exception: it's written back to its own location, including inside a folder. See Save a notebook to H2O Drive.
  • Only notebooks and text files are supported. The H2O Drive tab handles .ipynb notebooks and UTF-8 text files, such as .py, .csv, .json, and .md. Every other file type, including images, archives, Parquet files, and model files, is treated as text, so don't open one from the H2O Drive tab. Double-clicking a file of an unsupported type at the top level of your H2O Drive corrupts the H2O Drive object immediately. Right-clicking it and selecting Open writes nothing on its own, but the file is then open at its H2O Drive path, so the next save writes the corrupted copy back — and autosave counts as a save. Double-clicking one inside an H2O Drive folder corrupts only the local copy and leaves the H2O Drive object unchanged. To retrieve a file of an unsupported type, right-click it in the H2O Drive tab and select Download, which transfers the bytes of the object as they are.
  • A file added with Upload Files isn't the file you uploaded. The H2O Drive tab doesn't store an uploaded file in its original form, whatever the file type, so a text file opens as unreadable text, a notebook can't be opened at all, and downloading returns the stored object rather than your original file. For a file larger than 1 MB, JupyterLab uploads it in 1 MB chunks and each chunk replaces the last, so only the final chunk reaches H2O Drive — at most 1 MB, and often much less. Above 15 MB, JupyterLab asks you to confirm the upload first. Dragging files from your computer onto the H2O Drive tab has the same result. To put a notebook or a UTF-8 text file in H2O Drive, add it to the local workspace from the Local tab, open it, and use Save active notebook to H2O Drive instead, which writes to the top level of your H2O Drive. The H2O Drive tab has no way to put a file of any other type into H2O Drive: uploading stores something other than your file, and the save action requires opening the file, which corrupts it.
  • Only your personal H2O Drive storage is available. The H2O Drive tab browses your own H2O Drive files only. It can't browse H2O Drive workspace storage.
  • Checkpoints don't work in H2O Drive. The H2O Drive tab keeps no checkpoints, so reverting to a checkpoint reports No checkpoints for anything stored in H2O Drive. H2O Drive keeps no earlier versions of an object either, and autosave continuously overwrites the only copy of a notebook that is open directly on H2O Drive. Keep irreplaceable work in the local workspace, and save copies to H2O Drive deliberately.
  • Deleting is permanent. The confirmation dialog offers to move the file to trash, but H2O Drive has no trash. Deleting a file removes it immediately, and deleting a folder removes everything under it.
  • Copy and paste don't work between the two tabs. Copy and paste across the Local and H2O Drive tabs isn't supported. The supported transfers are Save active notebook to H2O Drive; double-clicking a notebook inside an H2O Drive folder, which copies it to the local workspace; and right-clicking a file and selecting Download, after which you can add the downloaded file to the local workspace from the Local tab. If the browser saves the download as file with no extension, rename it first (see Troubleshooting).
  • Every listing reads all of your H2O Drive. Browsing the top level and browsing a folder both read every object in your H2O Drive and then filter the results, so folders don't make listings faster. Each browse, refresh, open, rename, delete, and create operation repeats this, and the H2O Drive tab also refreshes its listing about every 10 seconds while the browser tab is in the foreground, so these actions slow down as your H2O Drive grows. A thin bar at the top of the file listing marks a request in flight; quick requests show no bar.
  • Renaming replaces an object that already has the new name. Renaming a file to a name that another object in the same folder already uses replaces that object, without asking you to confirm, and you can't recover it. Dragging a file onto a folder inside the H2O Drive tab does the same. Renaming a folder onto an existing folder name merges the two and replaces the objects whose names collide. Check the listing for the name you're about to use before you rename. A rename that replaces an object never reports an error, so a Rename Error message doesn't mean the name was already taken.
  • Renaming a folder copies each object in turn. Each object is downloaded, uploaded under the new name, and then removed, so renaming is slow for large folders. If you close the browser tab partway through, some objects keep the old name.
  • You can't duplicate a folder. Duplicate works on single files only.
  • New folders contain a placeholder object. Creating a folder writes a hidden .h2odrive-keep object, because H2O Drive stores objects rather than folders. The Files panel hides the placeholder, but it can appear in other tools that list your H2O Drive.

H2O Drive troubleshooting​

The following table lists messages and symptoms you might see when you work with H2O Drive, and how to resolve them.

Message or symptomResolution
The H2O Drive tab doesn't appear in the Files panelYour engine image doesn't include the integration. See Prerequisites, and ask your administrator which of the images available to you includes it.
Could not open from H2O Drive or Could not save to H2O DriveThe H2O Drive request failed. Check that the file still exists in H2O Drive and try again. If every action fails, see the Every H2O Drive action fails row. This error can also appear after a save that succeeded: use File > Save Notebook for a notebook that is open directly on H2O Drive.
Every H2O Drive action failsCheck the Shared field on the Engine Details panel. A shared engine runs without your H2O AI Cloud credentials: pause the engine, turn off Shared, and resume it (see Prerequisites). If the engine isn't shared, it didn't receive the H2O AI Cloud credentials that H2O Drive needs. If it was last resumed automatically rather than by you, pause it and resume it yourself, which reissues your credentials. If that doesn't help, the remaining causes are configuration your administrator controls, so ask your administrator to check that H2O Drive is available in your environment.
No active documentOpen the notebook or file you want to save, click its tab in the JupyterLab main work area to make it the active document, and then save it to H2O Drive.
Could not create a notebook in H2O Drive or Could not create a folder in H2O DriveThe H2O Drive request failed. Refresh the listing and try again.
The H2O Drive tab is blankAn empty H2O Drive shows an empty listing with no message. Click Refresh H2O Drive listing. If the listing stays blank and you expect files, H2O Drive might be unreachable from your engine. Contact your administrator.
The browser saves a downloaded file as file, with no extensionRename the downloaded file and add the original extension.
The content of a file you opened or saved is garbledIf you added the file with Upload Files, or by dragging it onto the H2O Drive tab, see the next row. Otherwise the file type isn't supported: the H2O Drive tab supports .ipynb notebooks and UTF-8 text files only.
A file you added with Upload Files, or by dragging it onto the H2O Drive tab, isn't the file you uploadedUploaded files aren't stored in their original form (see Limitations). Delete the uploaded object. For a .ipynb notebook or a UTF-8 text file, add it to the local workspace from the Local tab, open it, and use Save active notebook to H2O Drive instead. The H2O Drive tab can't put a file of any other type into H2O Drive.
Rename Error or Delete FailedThe H2O Drive request failed partway. Click Refresh H2O Drive listing to see what changed, then try again. After a failed folder rename, some objects can still carry the old name; retrying the rename moves the rest.
A file you renamed replaced another fileRenaming onto a name that another object in the same folder already uses replaces that object, without asking you to confirm, and the replaced object can't be recovered. See Limitations.
Paste ErrorPasting into H2O Drive failed. You can't paste a folder within H2O Drive, and you can't paste between the Local and H2O Drive tabs.
Upload Error or Duplicate fileThe H2O Drive request failed. Refresh the listing and try again. Duplicate file also appears when duplicating fails outright — for example, when you try to duplicate a folder, which isn't supported (see Limitations).

Enterprise h2oGPTe assistant limitations​

The following limitations apply when you use the assistant:

  • The assistant works on whichever notebook is active as each change is applied. The target notebook is resolved separately for every operation in a set, not once when the set is proposed. If you switch notebooks while you wait for a reply, or between the confirmation card appearing and clicking Apply, the operations land in the notebook that is active then — and one set can be split across two notebooks. Open the notebook you want the assistant to work on, or ask it to create one, and leave it active.
  • The assistant sees a clipped view of your notebook. Cell source is clipped to 1,500 characters per cell and text outputs to 600 characters per cell, so in a notebook with long cells or long outputs the assistant works from a partial view and can propose code that misses what a clipped part defines. For a large notebook, split it or start a notebook that holds only the cells the task needs.
  • One request does one chunk of work. The assistant usually proposes one set of changes, applies them once you approve, and then ends the request — even when the task isn't finished. Ask the assistant to continue. On its own it takes at most eight turns per request, and only to fix an error in a cell it ran or to finish a reply that was cut off.
  • Applying a set of changes isn't all-or-nothing. The assistant applies each operation in turn and carries on after one fails, so a set can be applied in part — and a later operation can depend on something an earlier one didn't create. When that happens the result reads Applied with N error(s) and the per-operation detail is expanded automatically, so you can see which operations failed. Reject is the only all-or-nothing choice: it applies nothing.
  • The assistant doesn't see errors from Run all cells. It reads the results of the individual cells it runs, but running the whole notebook returns no results to it, so it doesn't notice or correct an error that only a Run all cells operation produced. Run the failing cell on its own, or tell the assistant what the error says.
  • Each turn times out after 180 seconds. The limit applies to a single exchange with h2oGPTe, not to your whole request, so an agent-mode request that takes several turns can keep working for much longer. A local session has no time limit. A turn that fails reports the reason, such as Error: h2oGPTe did not respond within 180s — please try again. See Troubleshooting.
  • A long-running cell blocks the turn. The 180-second limit covers only the exchange with h2oGPTe, not the cells the assistant runs. A cell that trains a model for 40 minutes keeps the panel busy for those 40 minutes, and Stop doesn't interrupt it — use Kernel > Interrupt Kernel.
  • Answers appear all at once. When the conversation is stored in h2oGPTe, the assistant returns each answer complete rather than streaming it, so a long answer takes a while to appear. The animated indicator shows that the assistant is still working. A local session streams answers as they're generated.
  • A cut-off answer is continued automatically. In agent mode, if a reply is cut off in the middle of a code block, the assistant reports Response was cut off — continuing… and takes another turn, which counts toward the eight-turn limit. Chat mode doesn't continue automatically.
  • The Collection list shows at most 100 collections. The panel requests at most 100 of the collections you can access in h2oGPTe. That set isn't limited to collections you own — it also includes collections shared with you, collections shared with a group you belong to, and public collections. A collection outside the first 100 isn't in the list, and you can't ground the assistant in it from the panel. Use h2oGPTe directly for work that needs such a collection. If you have more than 100 collections, the panel can also fail to find the existing h2oGPTe Notebook Agent collection and create another collection with the same name each time JupyterLab loads.
  • Code runs in your own kernel. The assistant runs the cells it proposes in the kernel of your notebook, so any file it writes, package it installs, or request it makes affects your engine.

Enterprise h2oGPTe assistant troubleshooting​

The following table lists messages and symptoms you might see when you use the assistant, and how to resolve them.

Message or symptomResolution
The h2oGPTe tab doesn't appear in the JupyterLab right sidebarYour engine image doesn't include the assistant. See Prerequisites, and ask your administrator which of the images available to you includes it.
h2oGPTe is not available in this environment — the assistant is disabled here. and the placeholder h2oGPTe is not availableThe panel couldn't reach h2oGPTe when it started, and stays unavailable until you reload the page. Check the Shared field on the Engine Details panel: if the engine is shared, pause it, turn off Shared, and resume it (see Prerequisites). If it isn't shared, and reloading doesn't help, your engine didn't receive the H2O AI Cloud credentials that the assistant needs. If the engine was last resumed automatically rather than by you, pause it and resume it yourself, which reissues your credentials. If that doesn't help, the remaining causes are configuration your administrator controls, so ask your administrator to check that h2oGPTe is available in your environment.
The status line reads Local session (h2oGPTe history unavailable)The assistant couldn't reach the chat history of h2oGPTe when the panel started. You can keep working, but the conversation isn't stored, the Chats and Collection controls are hidden, and the conversation is lost when you reload the page. Reload the page to try to reconnect.
Error: h2oGPTe did not respond within 180s — please try again.A turn reached the 180-second limit. Break the request into smaller steps and send it again. In a local session this error never appears because a local session has no time limit; if a local-session request doesn't return, click Stop.
(h2oGPTe returned an empty response)h2oGPTe returned an empty reply. Send the request again, or break it into smaller steps. Agent mode can also show this in place of a failed turn's real message: clear Agent mode in Settings and send the request again to see the underlying error.
No models available in the Model listThe h2oGPTe deployment responded but offers no model for your account. The panel stays open, but sending a message fails. Contact your administrator.
Failed to load models in the Model listThe model list couldn't be loaded. The panel then switches to the not-available state, so this message is rarely visible. Reload the page, and contact your administrator if the problem continues.
Failed to load chats: <error> in the Recent chats listThe chat list couldn't be loaded from h2oGPTe. Reload the page. If it keeps failing, keep working — new messages still reach h2oGPTe — and contact your administrator.
Failed to load conversation: <error> after selecting a chatThe transcript of that chat couldn't be loaded. Reload the page and open the chat again.
Renaming or deleting a chat appears to do nothingThe request to h2oGPTe failed, and the panel reports nothing. Reload the page to see the current list, then try again.
No active notebook — open a notebook to use agent mode.Agent mode acts on the notebook you have open. Open a notebook and send the request again, or ask the assistant to create one.
The assistant keeps proposing the same wrong codeh2oGPTe holds the conversation, so a failed attempt keeps steering later turns. Click + New to start a fresh conversation, then restate the request with the constraint that was missing. + New doesn't restore the confirmation card: if you clicked Apply all this session, reload JupyterLab as well.
The assistant stops partway through a taskExpected for a large task: one request does one chunk of work (see Limitations). Ask the assistant to continue, or send the task as a series of smaller requests so each one finishes in a single turn.
The assistant applies changes without askingYou clicked Apply all this session, which turns off the confirmation card until you reload JupyterLab in your browser.
Feedback