OpenParable
Skip to content
← Back to skills

Troubleshooting

Testing & Quality
troubleshooting

Troubleshooting is an Agent Skill for testing & quality published in the cartography-cncf/cartography repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Diagnose and fix common Cartography intel-module errors — `ModuleNotFoundError`, `PropertyRef validation failed`, `GraphJob failed`, missing relationships, MatchLink misses, cleanup deleting too much, slow queries, ignored custom schema fields, key errors during transform. Use when the user reports an error while developing or running a Cartography module.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cartography-cncf/cartography/blob/HEAD/.agents/skills/troubleshooting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/troubleshooting, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

troubleshooting

Diagnostic playbook for the most common errors encountered while developing Cartography intel modules.

Common issues and solutions

Import errors

# Problem: ModuleNotFoundError for your new module
# Solution: ensure __init__.py files exist in all directories
cartography/intel/your_service/__init__.py
cartography/models/your_service/__init__.py

Checklist:

  • __init__.py exists in cartography/intel/your_service/
  • __init__.py exists in cartography/models/your_service/
  • Module is imported in the parent __init__.py if needed

Schema validation errors

# Problem: "PropertyRef validation failed"
# Solution: check dataclass syntax and PropertyRef definitions
@dataclass(frozen=True)  # do not forget frozen=True
class YourNodeProperties(CartographyNodeProperties):
    id: PropertyRef = PropertyRef("id")  # must have type annotation
    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)

Common causes:

  • Missing frozen=True in @dataclass.
  • Missing type annotation (: PropertyRef).
  • Typo in the PropertyRef field name.

Relationship connection issues

# Problem: relationships not created
# Solution: ensure target nodes exist before creating relationships

# Load parent nodes first:
load(neo4j_session, TenantSchema(), tenant_data, lastupdated=update_tag)

# Then load child nodes with relationships:
load(neo4j_session, UserSchema(), user_data, lastupdated=update_tag, TENANT_ID=tenant_id)

Debugging steps:

  1. Check the target node label matches exactly.
  2. Verify target_node_matcher keys match the target node's property names.
  3. Ensure the value in your data dict or kwargs is not None.

Cleanup job failures

# Problem: "GraphJob failed" during cleanup
# Solution: check common_job_parameters
common_job_parameters = {
    "UPDATE_TAG": config.update_tag,  # must match what is set on nodes
    "TENANT_ID": tenant_id,           # if using scoped cleanup (default)
}
# Problem: cleanup deletes too much (wrong scoped_cleanup setting)
# Solution: verify scoped_cleanup is appropriate

@dataclass(frozen=True)
class MySchema(CartographyNodeSchema):
    # tenant-scoped resources — default, do not specify
    # scoped_cleanup: bool = True

    # global resources only — rare
    scoped_cleanup: bool = False  # vuln data, threat intel, etc.

For details on when to override scoped_cleanup, see the add-node-type skill.

Data transform issues

# Problem: KeyError during transform
# Solution: handle required vs optional fields correctly
{
    "id": data["id"],              # required — let it fail
    "name": data.get("name"),      # optional
    # avoid empty-string defaults — they hide missing data
    # "email": data.get("email", ""),
    "email": data.get("email"),    # use None default
}

Schema definition issues

# Problem: adding custom fields to schema classes
# Solution: remove them — only standard fields are recognised

@dataclass(frozen=True)
class MyRel(CartographyRelSchema):
    # Remove custom fields — they are silently ignored:
    # conditional_match_property: str = "some_field"
    # custom_flag: bool = True
    # extra_config: dict = {}

    # Keep only the standard relationship fields
    target_node_label: str = "TargetNode"
    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(...)
    direction: LinkDirection = LinkDirection.OUTWARD
    rel_label: str = "CONNECTS_TO"
    properties: MyRelProperties = MyRelProperties()

For the standard schema fields, see the add-node-type skill.

Performance issues

# Problem: slow queries
# Solution: index frequently queried fields
email: PropertyRef = PropertyRef("email", extra_index=True)

# Query on indexed fields when possible
MATCH (u:User {id: $user_id})  # good — id is always indexed
MATCH (u:User {name: $name})   # bad — name might not be indexed

Fields used inside a target_node_matcher are indexed automatically.

MatchLink issues

# Problem: MatchLinks not creating relationships
# Solution: both source and target nodes must exist first

load(neo4j_session, SourceNodeSchema(), source_data, ...)   # 1. source nodes
load(neo4j_session, TargetNodeSchema(), target_data, ...)   # 2. target nodes

load_matchlinks(                                            # 3. then MatchLinks
    neo4j_session,
    YourMatchLinkSchema(),
    mapping_data,
    lastupdated=update_tag,
    _sub_resource_label="AWSAccount",
    _sub_resource_id=account_id,
)
# Problem: MatchLink cleanup not working
# Solution: use GraphJob.from_matchlink with the right args
GraphJob.from_matchlink(
    YourMatchLinkSchema(),
    "AWSAccount",                          # _sub_resource_label
    common_job_parameters["AWS_ID"],       # _sub_resource_id
    common_job_parameters["UPDATE_TAG"],   # update_tag
).run(neo4j_session)

For full MatchLink details, see the add-relationship skill.

Debugging tips

  1. Check existing patterns first. Look at similar modules in cartography/intel/ before inventing new ones.
  2. Verify imports. All CartographyNodeSchema / CartographyRelSchema imports must point to cartography.models.core.*.
  3. Test transform functions with real API responses.
  4. Validate Cypher in Neo4j Browser when relationships are not appearing.
  5. Check file naming. Module files should match the service name (cartography/intel/lastpass/users.py).
  6. Run tests incrementally. After each change, run the integration test.
  7. Test through sync(), not isolated load() calls.

Key files

FilePurpose
cartography/client/core/tx.pyCore load() and load_matchlinks() — query generation lives here
cartography/graph/job.pyGraphJob cleanup operations
cartography/models/core/common.pyPropertyRef definition
cartography/models/core/nodes.pyCartographyNodeSchema, CartographyNodeProperties, ExtraNodeLabels, etc.
cartography/models/core/relationships.pyCartographyRelSchema, LinkDirection, matchers, MatchLinks
cartography/config.pyConfig object — check missing fields here
cartography/cli.pyTyper CLI with help panels
cartography/data/indexes.cypherManual index definitions (legacy)
cartography/data/jobs/cleanup/Legacy cleanup JSON files
cartography/analysis/*/analysis.pyTyped analysis jobs (see analysis-jobs skill)
cartography/data/jobs/analysis/Legacy migration/cleanup JSON jobs
cartography/data/jobs/scoped_analysis/Legacy scoped migration/cleanup JSON jobs

Test utilities

from tests.integration.util import check_nodes, check_rels


# Nodes
expected_nodes = {
    ("user-123", "[email protected]"),
    ("user-456", "[email protected]"),
}
assert check_nodes(neo4j_session, "YourServiceUser", ["id", "email"]) == expected_nodes


# Relationships
expected_rels = {
    ("user-123", "tenant-123"),
    ("user-456", "tenant-123"),
}
assert check_rels(
    neo4j_session,
    "YourServiceUser", "id",
    "YourServiceTenant", "id",
    "RESOURCE",
    rel_direction_right=True,
) == expected_rels

Error message reference

Error messageLikely causeSolution
PropertyRef validation failedMissing type annotation or frozen=TrueCheck dataclass definition
Node not found for relationshipTarget node does not existLoad parent nodes first
GraphJob failedWrong common_job_parametersCheck UPDATE_TAG and tenant ID
KeyError: 'field_name'Required field missing in API responseUse .get() for optional fields
ModuleNotFoundErrorMissing __init__.pyAdd __init__.py to all directories
Relationship not createdMatcher property mismatchVerify property names match exactly

When to ask for help

Stop and ask the user when:

  • Legacy Cypher queries contain unclear business logic.
  • Complex relationships do not map clearly to the data model.
  • Tests keep failing after multiple attempts.
  • Multiple modules look interdependent.
  • Performance issues persist after adding indexes.
  • The graph contains unexpected data after sync.