Running on Confluence?

Confluence permissions tangled or macros broken? We clear the backlog.

Confluence works until a space gets inherited permissions from three directions, a macro from Server breaks on Cloud, or a Marketplace app stops rendering after an upgrade. We untangle the space permissions, rewrite the macros against the current editor, and bring the page tree back to something the team can navigate.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

confluence-migration.log

still failing

What it is

Confluence at a glance

Confluence is a wiki and team documentation platform first released by Atlassian in 2004. It has grown into the default internal documentation tool for teams already using Jira, with Cloud, Data Center and (now retired) Server editions covering different hosting models. The Cloud edition is the active focus for Atlassian, and Server reached end of support in February 2024.

The platform covers spaces (top-level containers, often per team), pages organised in a tree, blog posts, comments, inline comments, mentions, tasks, templates, macros, Smart Links, a native ADF (Atlassian Document Format) editor, Marketplace apps, and REST APIs v1 and v2 with Confluence Connect and Forge for app development. It supports SAML SSO through Atlassian Access, SCIM provisioning, data residency, and tight integration with Jira. Common problems we see come from three directions: space permission schemes that have grown into inheritance tangles, macros and Marketplace apps that broke on the Server to Cloud migration, and page trees that have grown past what team members can browse without heavy search.

Type
Team wiki and documentation platform
First released
2004
License
Proprietary SaaS (Cloud) and commercial on-premises (Data Center), per-user pricing
Maintained by
Atlassian
Typically used for
Internal documentation, runbooks, product specs, meeting notes, knowledge bases, team home pages

The honest version

Confluence pros and cons

No technology is all upside. This is where Confluence earns its place and where it tends to cause trouble.

Where Confluence is strong

  • Deep integration with JiraIssue links, inline issue previews, epics on roadmaps, and release notes generated from Jira queries make Confluence the natural companion for teams already using Atlassian.
  • Spaces scale to large organisationsPer-team or per-product spaces with their own permissions and templates let a company of thousands run many separate workspaces under one tenant without stepping on each other.
  • A huge MarketplaceDraw.io, Scroll Documents, Comala Workflows, Gliffy and hundreds of other apps extend the editor and the admin surface, covering diagrams, approvals, publishing and content governance.
  • Native ADF editor is goodThe modern editor handles tables, code blocks, decision cards, task lists and Smart Links cleanly, and the mobile experience is passable.
  • Enterprise administration is strongAtlassian Access adds SAML SSO, SCIM provisioning, enforced two-factor authentication, data residency and audit logs. Security teams in regulated industries can get to yes.
  • Forge for modern app developmentAtlassian's Forge platform lets teams build and deploy Confluence Cloud apps against a hosted runtime, which beats building against the older Connect model for most new work.

Where Confluence bites

  • Permissions schemes get out of controlSpace permissions, page restrictions, group inheritance and Atlassian Access rules combine into a model that even experienced admins have to diagram to reason about. Access bugs are common.
  • Cloud migrations lose macros and appsThe Server to Cloud migration assistant does a lot, but not everything comes across. Marketplace apps may have no Cloud equivalent, custom macros fail silently, and attachments can land in the wrong space.
  • Search is only okayFull-text search works, but ranking and scoping options are limited, and a large tenant with many spaces returns too many results of unclear relevance. Third-party search Marketplace apps often fill the gap.
  • Page trees grow into mazesWithout an information architecture discipline, spaces accumulate pages for years and the tree becomes unnavigable. Teams end up using Google to find Confluence pages.
  • Marketplace apps age unpredictablyServer apps are unmaintained now; Cloud apps shift as the platform shifts, and an app that was essential three years ago can be deprecated with short notice, leaving teams scrambling for a replacement.
  • Export to PDF or Word is fragileNative exports work well for short pages and poorly for anything with Smart Links, custom macros or Marketplace content. Teams often rely on Scroll or K15t apps for serious publishing, which adds cost and complexity.

Sound familiar?

Common Confluence problems we fix

The Confluence problems that bring people to us, and what you have once each one is fixed.

AccessDenied: user lacks 'Add Pages'

Users cannot edit a space that should be open to them

A permissions scheme where group membership grants the user access at the org level but the space permission denies them, or inherited page restrictions from a parent page that block edits in a subtree. The user is told to ask an admin, which does not scale.

Permissions aligned with intent

macro 'content-by-user' unavailable

Server macros do not survive the Cloud migration

A legacy Server macro that has no Cloud equivalent, or a Marketplace app that stopped at Server. The page renders a placeholder where important content used to be, and nobody flagged it during migration review.

Macros rebuilt or replaced

Marketplace app failed to load

A Marketplace app stops working after an upgrade

An app that was compatible with the previous Confluence Cloud release but fails against the current one, or a Forge app that needs permissions it did not previously require. Pages that depend on it render empty frames.

App compatible with current platform

space permission scheme: 38 groups, 6 missing

Space permissions reference deleted groups

A space with permissions granted to groups that no longer exist in the identity provider, or groups that were renamed. The scheme looks complex but much of it is dead weight.

Permissions audited and simplified

migration assistant: 142 pages failed

Cloud migration leaves pages behind

A migration with invalid attachment references, ADF content that the Cloud editor rejects, or spaces that exceed the single-run size limit. The admin sees a 'completed with errors' status and has to reconcile manually.

Migration completed, gaps filled

REST API v2 returns 403

An integration loses access after an API version change

An automation that was using REST v1 endpoints and switched to v2 without the space-scoped permission the v2 endpoint requires, or an app with an OAuth 2.0 scope that is narrower than the token it replaces.

API integration on correct scopes

PDF export timed out at 90s

Space export fails for large pages

A space export or a per-page PDF that exceeds the generation timeout, usually because of many images, many Smart Links or a very long page. The export job completes with half the content missing.

Exports chunked and reliable

ADF: unsupported node type

An imported or pasted page fails to render

Content pasted from an external source, or imported from a legacy export, containing ADF node types the current editor does not recognise. The page saves but some sections render as empty boxes.

Content cleaned to current ADF

What we do

Confluence help, from migration to hygiene

Call us for one failing macro, or let us own the whole Confluence tenant.

Rescue
A space locked down by accident, macros that stopped working after an upgrade, or a Marketplace app refusing to load. We get the pages usable first and explain the cause second.
Permissions clean-up
Space permission schemes mapped, dead groups removed, page restrictions audited, and a convention agreed so new spaces inherit a known baseline rather than drifting.
Server to Cloud migrations
Full tenant migrations with macros audited against Cloud equivalents, Marketplace app replacements chosen, content gaps filled, and a cutover plan that does not drop people's work.
Information architecture
Space taxonomy agreed, page templates created, labels and categorisation enforced, and a search strategy that makes the tenant actually findable.
Forge and Connect app development
Custom macros, admin tools, workflow integrations and content automation built as Forge apps against the current platform, with the review and publishing process taken off your plate.
Managed Tech
Monthly permission audits, Marketplace app compatibility checks, migration drills ahead of major Cloud releases, and an engineer on call when Atlassian ships a change that reshapes the editor or the API.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Confluence alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Confluence questions

Something else? Call+1 737 727 7327

How do we untangle Confluence space permissions?

By starting from intent rather than from the current state. For each space, write down who should have what level of access, map that to a minimal set of groups in the identity provider, and apply a simple permission scheme. Most tenants we see have accumulated layers of exceptions, and the audit removes more than it adds. Page-level restrictions should be rare and justified rather than a workaround for a missing group.

What breaks when we migrate from Confluence Server to Cloud?

The migration assistant handles pages, spaces, attachments and most of the common macros. The usual casualties are legacy Server macros that have no Cloud equivalent, Marketplace apps that never shipped a Cloud version, and large attachments that exceed size limits. We audit the tenant before migration so you know what will not come across and plan replacements in advance.

Why does a Confluence Cloud page render empty where a macro used to be?

The macro is either not available in Cloud, is provided by a Marketplace app that was uninstalled during migration, or has been deprecated by a recent Confluence release. The page shows a placeholder or nothing at all. The fix is usually to replace the macro with a native equivalent (Smart Link, inline content) or with a Forge app that reimplements the behaviour on the modern platform.

Can we build a custom Confluence macro or integration?

Yes, through Forge for Cloud or the Connect framework for legacy work. Forge is the right choice for most new builds: the runtime is hosted by Atlassian, authentication is handled, and the macro can live on your side as a small app rather than as a Confluence plugin. We design, build, submit to the Marketplace or install privately, and keep the app compatible across platform changes.

How do we make Confluence search actually useful?

By imposing some information architecture: consistent labels, templates for common page types, and a space taxonomy that aligns with how people look for content. Native search works better when the content is structured. For larger tenants, Marketplace search apps improve ranking and scoping, but the content hygiene is the bigger lever.

How much does Confluence help cost?

The quote is free. Describe the tenant edition, the size of the move or the problem, and we come back with a scope and a fixed price before anyone touches the pages.

Free estimate

Confluence giving you trouble?

Space permission audits, Cloud migrations, Forge app development and information architecture. We work on the whole tenant rather than one space at a time.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.