Images uploaded in my HubSpot CMS environment keep getting cropped

[TMisuna]

I’m looking for clues because I can’t identify the root cause.

Situation

• The issue occurs only with images that live inside my custom theme.

• The theme is connected to Design Manager, and all theme source code, image assets, and CSS files are version-controlled in Git.

Workflow

When I start development or maintenance work, I always pull the latest changes with:

npx hs fetch --overwrite theme-name theme-name

Symptoms

• After running the command above, some image directories inside the theme are fetched as “differences,” even though I haven’t touched them.

• Of those images:

  • Some appear unchanged.

  • Others mysteriously have part of the image missing or “cropped.”

This makes me think the Design Manager copy and my Git copy are somehow diverging, but I can’t pinpoint why. I’m wondering if the watch command (auto-watch & upload) could be involved.

Temporary fix

If an image is corrupted, I can restore it with:

npx hs upload theme-name theme-name

This uploads the intact local asset and overwrites the corrupted one.

 

Question

Why does this keep happening?

• Has anyone seen a similar case?

• Could it be an operational mistake on my side?

• What mechanisms (fetch, watch, caching, etc.) might cause random image files in a theme to become partially overwritten or corrupted on fetch?

Any insights or past experiences would be greatly appreciated.

[Anton · Accepted solution]

Hey @TMisuna,

never run into this and it's very interesting that it happens during the "fetch" command. Because this means it's related to HubSpot, as you fetch from HS, not from GitHub. 

If you have set up the continuous GitHub integration, the default workflow is: that every "hs upload..." will upload it to GitHub and the GitHub action pushes it to HubSpot. But fetching will fetch from HS, not GitHub.

Years ago, I had a super hard time working with the CI, when I was developing a custom theme and had to wait 1-2 minutes to see the changes in HubSpot, every time I saved a file (I think there was no local server back then),... This is why I've changed my workflow to:

• set up a cms sandbox account (app test account) here: developers.hubspot.com
• Run "hs watch --account=HUB_ID_OF_SANDBOX ..." in a terminal
• once a feature is fully developed and approved, I manually push it to GitHub and let the GitHub action upload it to the live portal

When it comes to images, I'm trying to use SVGs where-ever possible. I'm also not using .webP format as it can only be opened/modified with design tools like Photoshop outside of a browser. So a marketer/content-editor, who doesn't have access to such tools can't use them. Sure they're mostly preview images, but still... 

hope this helps

best, 

Anton

p.s. A developer account (the one you create on developers.hubspot.com) can have upto 10 or 20 (not sure) test accounts. This means you can have one developer account and 10/20 test accounts (cms sandboxes) -> 10/20 seperate client approval portals within one portal

[Nhal]

That’s super frustrating! I’ve been burned by hs fetch clobbering stuff too. Are you running hs watch before the fetch finishes?

Try this:
Kill any running hs watch before hs fetch --overwrite, then restart watch after. That fetch can trigger a weird sync loop if watch is live—Design Manager pushes up junk or stale files right as you’re pulling.

I once had a JPG randomly zero out after a fetch because hs watch caught a partial write mid-sync. Let me know if pausing watch helps.

[kosalaindrasiri · Accepted solution]

Hey @TMisuna,

Potential Causes

1. CLI Fetch Behavior with Binary Files
   The hs fetch command is designed to retrieve theme files from HubSpot's Design Manager to your local environment. However, there have been reports of unexpected behavior when fetching binary files, such as images. In some instances, images fetched using the CLI appear corrupted or incomplete. This might be due to the way the CLI handles binary data during the fetch process.
   
   
2. Conflict Between Local and Remote Versions
   Using the --overwrite flag forces the local files to be replaced with the remote versions. If there are discrepancies between the local and remote repositories, especially with binary files, this could lead to corrupted images. The remote version may be incomplete or corrupted, and fetching it overwrites the intact local version.
   
   
3. Watch Command Interference
   The hs watch command monitors local files for changes and uploads them to HubSpot in real-time. If hs watch is running concurrently with hs fetch, there might be conflicts, especially if both commands are trying to access or modify the same files simultaneously. This could result in partial overwrites or corrupted files.

Also, you can manage image assets separately from your theme files. You can upload images directly through the HubSpot File Manager or use the CMS to manage these assets. This approach ensures that image assets are not affected by theme fetch operations.

Regards,

Kosala

[TMisuna]

Thank you for your reply. I still haven’t pinpointed the exact root cause, but learning that it might be related to how binary files are handled is a valuable clue. I appreciate the big hint!

[Anton · Accepted solution]

Hey @TMisuna,

never run into this and it's very interesting that it happens during the "fetch" command. Because this means it's related to HubSpot, as you fetch from HS, not from GitHub. 

If you have set up the continuous GitHub integration, the default workflow is: that every "hs upload..." will upload it to GitHub and the GitHub action pushes it to HubSpot. But fetching will fetch from HS, not GitHub.

Years ago, I had a super hard time working with the CI, when I was developing a custom theme and had to wait 1-2 minutes to see the changes in HubSpot, every time I saved a file (I think there was no local server back then),... This is why I've changed my workflow to:

• set up a cms sandbox account (app test account) here: developers.hubspot.com
• Run "hs watch --account=HUB_ID_OF_SANDBOX ..." in a terminal
• once a feature is fully developed and approved, I manually push it to GitHub and let the GitHub action upload it to the live portal

When it comes to images, I'm trying to use SVGs where-ever possible. I'm also not using .webP format as it can only be opened/modified with design tools like Photoshop outside of a browser. So a marketer/content-editor, who doesn't have access to such tools can't use them. Sure they're mostly preview images, but still... 

hope this helps

best, 

Anton

p.s. A developer account (the one you create on developers.hubspot.com) can have upto 10 or 20 (not sure) test accounts. This means you can have one developer account and 10/20 test accounts (cms sandboxes) -> 10/20 seperate client approval portals within one portal

[TMisuna]

Thank you for your response. I found several aspects of your development workflow that I’d like to adopt myself. I appreciate the valuable insights you shared.