Troubleshooting

Common issues and solutions

This page covers common issues encountered when using cpaltemplates and their solutions. Topics include installation problems, font rendering, theme application, color scales, tables, interactive plots, maps, and performance optimization.

If you can’t find a solution here, please report an issue on GitHub.

Installation Issues

Package Not Found

# Error: package 'cpaltemplates' is not available

Solution:

# Install remotes if needed
install.packages("remotes")

# Install with dependencies
remotes::install_github(
  "childpovertyactionlab/cpaltemplates",
  dependencies = TRUE
)

R Version Error

# Error: package requires R >= 4.3.0

Solution:

Update R to version 4.3.0 or higher. Download from CRAN.

Dependency Conflicts

# Error: dependency 'xyz' is not available

Solution:

# Install dependencies manually
install.packages(c("ggplot2", "bslib", "gt", "reactable", "highcharter"))

# Then retry
remotes::install_github("childpovertyactionlab/cpaltemplates")

Font Issues

Fonts Not Rendering

Symptoms:

  • Plots show system fonts instead of Inter/Roboto
  • Warning: “font family not found”

Solutions:

# 1. Run font setup
setup_cpal_google_fonts(force_refresh = TRUE, verbose = TRUE)

# 2. Check font availability
sysfonts::font_families()

# 3. Verify showtext is enabled
library(showtext)
showtext_auto()

# 4. Check what font is being used
cpal_font_family(setup = TRUE)

PDF Font Issues

Symptoms:

  • Fonts don’t appear in PDF output
  • PDF shows rectangles instead of text

Solutions:

# Use cairo device for better font support
ggsave("plot.pdf", plot, device = cairo_pdf)

# Or use showtext
library(showtext)
showtext_auto()
ggsave("plot.pdf", plot)

Theme Issues

Theme Not Applying

Symptoms:

  • Plot doesn’t have CPAL styling
  • Default ggplot2 theme appears

Solutions:

# 1. Ensure theme_cpal() is in the plot
ggplot(data, aes(x, y)) +
  geom_point() +
  theme_cpal()  # Must be included!

# 2. Check if theme is being overwritten
# theme_cpal() should be last or near-last
ggplot(data, aes(x, y)) +
  geom_point() +
  other_layer() +
  theme_cpal() +  # After other layers
  theme(specific_override = ...)  # Specific overrides after

# 3. Set default theme for session
set_theme_cpal()

Shiny Theme Not Working

Symptoms:

  • Dashboard shows default Bootstrap styling
  • CPAL colors not appearing

Solutions:

# 1. Ensure using bslib page functions
page_sidebar(  # Correct - bslib function
  theme = cpal_dashboard_theme(),
  ...
)

fluidPage(  # Wrong - doesn't support bslib themes fully
  ...
)

# 2. Check bslib is loaded
library(bslib)

# 3. Verify theme is applied
theme <- cpal_dashboard_theme()
print(theme)  # Should show theme details

Color Issues

Colors Not Showing

Symptoms:

  • scale_color_cpal() has no effect
  • Default ggplot2 colors appear

Solutions:

# 1. Match discrete/continuous to your data
# For categorical data:
scale_color_cpal("main", discrete = TRUE)

# For continuous data:
scale_color_cpal_c("teal_seq_5")

# 2. Check palette name is valid
list_cpal_palettes()

# 3. Verify color aesthetic is mapped
ggplot(data, aes(x, y, color = group)) +  # color must be mapped
  geom_point() +
  scale_color_cpal("main")

Wrong Number of Colors

Symptoms:

  • “Insufficient values in manual scale” error
  • Colors don’t match number of categories

Solutions:

# Check how many categories you have
n_distinct(data$category)

# Use appropriate palette
# For 3 categories:
scale_color_cpal("main_3")

# For 5 categories:
scale_color_cpal("main_5")

# For 6 categories:
scale_color_cpal("main_6")  # 6 colors

Color Contrast Issues

# Check if colors meet accessibility standards
validate_color_contrast("#007A8C", "#FFFFFF")

# Check all brand colors
validate_brand_colors()

Table Issues

GT Table Not Displaying

Symptoms:

  • Table doesn’t render in viewer
  • Error about gt package

Solutions:

# 1. Install gt
install.packages("gt")

# 2. Verify installation
library(gt)

# 3. Check data is a data frame
class(your_data)  # Should be "data.frame" or "tbl_df"

Reactable Not Interactive

Symptoms:

  • Table appears static
  • No search/pagination

Solutions:

# 1. Install reactable
install.packages("reactable")

# 2. In Shiny, use correct output function
# UI:
reactableOutput("table")

# Server:
output$table <- renderReactable({
  cpal_table_reactable(data)
})

Interactive Chart Issues (Highcharter)

For interactive charts, cpaltemplates uses Highcharter. See the Highcharter Gallery for examples and Themes & Styling for theming details.

Highcharter Not Rendering

Symptoms:

  • Chart doesn’t appear
  • Error about highcharter package

Solutions:

# 1. Install highcharter
install.packages("highcharter")

# 2. Verify installation
library(highcharter)

# 3. Check basic chart works
hchart(mtcars, "scatter", hcaes(x = wt, y = mpg))

CPAL Theme Not Applying

Symptoms:

  • Chart shows default Highcharts styling
  • CPAL colors not appearing

Solutions:

# Apply CPAL theme to chart
hchart(data, "bar", hcaes(x = category, y = value)) |>
  hc_cpal_theme() |>
  hc_colors_cpal("main") |>
  hc_add_cpal_logo()

# For dark mode
hchart(data, "bar", hcaes(x = category, y = value)) |>
  hc_cpal_theme("dark") |>
  hc_add_cpal_logo(mode = "dark")

Highcharter in Shiny

# UI:
highchartOutput("chart")

# Server:
output$chart <- renderHighchart({
  hchart(data, "column", hcaes(x = x, y = y)) |>
    hc_cpal_theme() |>
    hc_colors_cpal("main")
})

Map Issues

Map Not Displaying

Symptoms:

  • Empty plot
  • Error about sf

Solutions:

# 1. Install sf
install.packages("sf")

# 2. Check data is sf object
class(geo_data)  # Should include "sf"

# 3. Verify CRS
sf::st_crs(geo_data)

# 4. Transform if needed
geo_data <- sf::st_transform(geo_data, 4326)

Mapbox Token Issues

# Set token
Sys.setenv(MAPBOX_PUBLIC_TOKEN = "pk.xxx...")

# Verify
Sys.getenv("MAPBOX_PUBLIC_TOKEN")

# Add to .Renviron for persistence
usethis::edit_r_environ()
# Add: MAPBOX_PUBLIC_TOKEN=pk.xxx...

Project Scaffolding Issues

Templates Not Copying

Symptoms:

  • Project created but missing files
  • Error about templates

Solutions:

# 1. Reinstall package
remotes::install_github("childpovertyactionlab/cpaltemplates")

# 2. Check templates exist
system.file("templates", package = "cpaltemplates")

# 3. Try with explicit path
start_project(
  "my-project",
  path = normalizePath("~/projects"),
  project_type = "analysis"
)

Project Won’t Open

# Disable auto-open
start_project("my-project", open = FALSE)

# Open manually
rstudioapi::openProject("my-project")

Brand File Issues

_brand.yml Not Found

# Copy from package
use_cpal_brand()

# Verify file exists
file.exists("_brand.yml")

Invalid Brand Configuration

# Validate the file
validate_cpal_brand(verbose = TRUE)

# Common issues:
# - Missing # in hex colors: "007A8C" should be "#007A8C"
# - Invalid YAML syntax: check indentation
# - Missing required sections

Performance Issues

Slow Rendering

Solutions:

# 1. Reduce DPI for drafts
save_cpal_plot(p, "draft.png", dpi = 100)

# 2. Simplify geometries for maps
geo_simple <- sf::st_simplify(geo_data, dTolerance = 100)

# 3. Sample large datasets
data_sample <- dplyr::slice_sample(large_data, n = 1000)

# 4. Set chart dimensions for Highcharter
hchart(...) |>
  hc_chart(height = 350)

Memory Issues

# Clear environment
rm(list = ls())
gc()

# Use data.table for large files
library(data.table)
data <- fread("large_file.csv")

Getting Help

Check Package Version

packageVersion("cpaltemplates")

Report Issues

GitHub Issues

When reporting, include:

  1. R version: R.version.string
  2. Package version: packageVersion("cpaltemplates")
  3. Operating system
  4. Minimal reproducible example
  5. Full error message

Reinstall Clean

# Remove and reinstall
remove.packages("cpaltemplates")
remotes::install_github(
  "childpovertyactionlab/cpaltemplates",
  dependencies = TRUE,
  force = TRUE
)

Quick Fixes Checklist

See Also