Over the past year, we’ve noticed some customers running into hiccups in their development and deployment workflows. Usually, it happens after switching to 64-bit HCL Notes clients without updating their Teamstudio Developer tools or products like CIAO! and Build Manager. The move to 64-bit is completely understandable - Notes 64-bit has come a long way, and with Notes 14 now available only in 64-bit, it’s become the new standard. But the transition does bring a few compatibility issues that are easy to overlook.
The easiest way to avoid those headaches is to coordinate your Teamstudio updates with any Notes or Domino upgrades. Keeping everything in sync helps ensure smooth deployments and a trouble-free development experience with your Teamstudio tools.
Which tools are you using?
Ensure compatibility of your Teamstudio tools prior to performing any Notes upgrades.
Why plan Teamstudio tool updates prior to initiating Notes client/server upgrades?
Benefits of planning: Updating Teamstudio tools at the same time as your Notes or Domino upgrades keeps everything working together smoothly. When your environments stay in sync, you’re far less likely to run into last-minute surprises with plug-ins, templates, or APIs. Coordinating upgrades also helps maintain continuity between development and deployment, so your team can keep moving without unexpected detours.
Having a clear upgrade plan makes recovery easier too. If anything does crop up during testing, you’ll know exactly how to fix it. And by staying current, you’ll always be aligned with supported versions, giving you access to the latest fixes, performance improvements, and full Teamstudio technical support.
Pitfalls when coordination is skipped: When Notes and Teamstudio upgrades aren’t planned together, things can get messy. We’ve seen cases where Notes upgrades overwrite or re-register components, which can leave Teamstudio menus, toolbars, or integrations missing the next time you launch. Architecture mismatches are another common headache. Older Teamstudio versions simply won’t load (or may even crash outright) on 64-bit Notes clients.
Now that Notes 14 is 64-bit only, and 64-bit support has been around since Notes 12, these issues are showing up more often during staggered or partial rollouts. A little coordination up front can save a lot of frustration later.
Upgraded your Notes clients but not Build Manager?
If you have moved to 64-bit clients but still use an older version of Build Manager, all build promotions will no longer work.
Small updates can cause big headaches:
Even minor Notes updates, like interim fixes or point releases, can cause trouble if they aren’t validated against your current Teamstudio versions. We’ve seen situations where an untested Notes update disrupts the CIAO! development workflow or stalls automated Build Manager jobs. Things get even trickier when some parts of the environment move to 64-bit while others stay on older versions. That kind of “environment drift” can introduce subtle compatibility issues that quietly undermine Teamstudio tools.
What you might notice:
After an uncoordinated upgrade, teams sometimes report missing or disabled Teamstudio menus and toolbars, build jobs that fail halfway through due to path or API changes, and CIAO! check-in or check-out errors that interrupt normal development. Scripts and integrations that still point to 32-bit paths, like “Program Files (x86)”, are especially vulnerable once clients switch to 64-bit installations.
How to upgrade Notes clients and Teamstudio tools the right way
Start with a quick pre-upgrade check. Take inventory of your current Notes client and Domino server versions, note whether they’re 32- or 64-bit, and make a list of all installed Teamstudio components and tools, including CIAO! and Build Manager server components).
Next, define your target Notes and Domino versions, and confirm that your Teamstudio tools are compatible, especially when moving to 64-bit. Look for dependencies that might be affected by architecture or path changes, things like plug-ins, templates, build steps, signing IDs, or CIAO! log and configuration databases. It’s also worth reviewing the Release Notes on our product download pages for details on feature changes between 32- and 64-bit versions. For example, Profiler doesn’t have a 64-bit version, and there have been updates to some Build Manager steps and features.
Then, set up a staging workstation. Upgrade Teamstudio to versions that explicitly support your target Notes and Domino releases, making sure to back up first and update any configuration databases or templates as needed. Always apply Teamstudio client-side tools after you’ve installed Notes updates and Fix Packs, and have your new Teamstudio activation keys ready to go.
Once installed, validate your key workflows from end to end. For CIAO!, test check-in/check-out and any release steps you use. For Build Manager, run a few representative promotions that include build steps, custom actions, template registry releases, signing, and other deployment tasks. Document anything that needs fixing, and test any other Teamstudio development tools used in day-to-day development activities.
Finally, before upgrading Notes clients and Teamstudio tools, back up local CIAO! log repositories, configuration databases, and important Notes files like notes.ini and workspace data. In most cases, you’ll update Notes (and any Fix Packs) first, then install or upgrade Teamstudio Tools. Make sure all Notes clients, Designer, Admin, and Notes, are closed before you begin. After installation, refresh design templates and double-check that all plug-ins are working properly—for example, verify that Designer integration is functioning as expected.
Designer Client integration intact?
Verify that your tools are still working and integrated with the Notes Designer Client.
As you move to a 64-bit Notes client in environments that use Teamstudio CIAO! Server or Build Manager, make sure to upgrade the Teamstudio server-side components first to a version that supports 64-bit. Skipping this step will cause promotions and automations to stop working as soon as clients switch to 64-bit, bringing deployments to a halt and interrupting development. For more details, check out our earlier blog post on upgrade steps for those products.
Run a quick post-upgrade check:
Once everything’s installed, take a few minutes to make sure it’s all working as expected. Confirm that Teamstudio menus and toolbars are visible, Designer integration works correctly, and each Teamstudio tool launches without issues. Try a few test runs, check files in and out with CIAO!, run a Build Manager pipeline, and watch for any unusual prompts, policy conflicts, or access problems.
If you do spot something, document the details and any steps you’ve taken when submitting a support ticket. That information helps us troubleshoot more effectively. And of course, if you need a hand at any point, we’re always here to help!
Handling incremental Notes client patches and interim fixes
Treat Fix Packs and interim patches as mini-upgrades. Even small changes can affect libraries or startup behavior, and that can quietly break tool functionality if you don’t test first. Always stage each patch on a test client, run through your verification checklist, and review both Teamstudio and HCL release notes for any known impacts.
It’s also best to turn off auto-updates on development workstations and schedule patching during low-risk windows. Coordinate timing with your development teams so updates don’t land in the middle of a sprint, and make sure everyone knows the plan: when it’s happening, what to expect, and how to roll back if needed.
We also recommend removing Teamstudio client-side tools before applying Notes Fix Packs, then reinstalling them afterward. It’s not always strictly necessary, but we’ve seen plenty of cases where a Fix Pack changes Notes components in ways that interfere with Teamstudio integrations. A quick reinstall avoids those surprises.
In short: plan, stage, test, and verify. Keeping your Teamstudio and HCL Notes/Domino environments in sync helps you avoid broken integrations, stalled builds, and unnecessary downtime, especially when moving to 64-bit or applying patches.
And if you ever have questions or run into an issue, don’t hesitate to reach out. We’re always happy to help.