문제 해결

이 페이지는 Quarto 사용 중 문제가 발생했을 때 활용할 수 있는 여러 전략을 정리합니다. 언제나 Quarto 이슈 트래커에 대한 피드백과 버그 보고를 환영하지만, 이 페이지가 빠른 문제 해결에 도움이 될 수 있습니다.

기본

quarto와 의존성 버전 확인

quarto check를 실행하면 Quarto와 의존성 버전을 확인할 수 있습니다. 아래는 출력 예시입니다:

Quarto 1.6.30
[✓] Checking environment information...
      Quarto cache location: /Users/cscheid/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.4.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.46.3: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.6.30
      Path: /Users/cscheid/repos/github/cscheid/quarto-regress/releases/v1.6.30/binQuarto 1.5.42

[✓] Checking tools....................OK
      TinyTeX: v2024.03.13
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/username/Library/TinyTeX/bin/universal-darwin
      Version: 2024

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.1
      Path: /.venv/bin/python3
      Jupyter: 5.7.2
      Kernels: julia-1.10, python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.3.3
      Path: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources
      LibPaths:
        - /Users/username/Library/R/arm64/4.3/library
        - /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
      knitr: 1.45
      rmarkdown: 2.26

[✓] Checking Knitr engine render......OK

스택 트레이스 받기

환경에 QUARTO_PRINT_STACK=true를 설정하면 오류가 발생했을 때 Quarto가 스택 트레이스를 출력합니다.

PowerShell에서:

$env:QUARTO_PRINT_STACK="true"

bash 계열 셸에서:

export QUARTO_PRINT_STACK=true

상세 로그 모드

환경에 QUARTO_LOG_LEVEL=DEBUG를 설정하면 Quarto가 내부 상태에 대한 더 많은 정보를 출력합니다.

PowerShell에서:

$env:QUARTO_LOG_LEVEL="DEBUG"

bash 계열 셸에서:

export QUARTO_LOG_LEVEL=DEBUG

명령줄에서 --log-level debug를 전달할 수도 있습니다. 예: quarto render index.qmd --log-level debug

로그를 파일로 기록하고 싶다면 환경에 QUARTO_LOG를 설정하거나 명령줄에서 --log를 사용하세요.

로그 파일 확인

Quarto는 문제 진단에 도움이 되는 로그 파일을 생성합니다. 로그 위치는 운영체제에 따라 다릅니다:

%LOCALAPPDATA%\quarto\logs

${HOME}/Library/Application Support/quarto/logs

$XDG_DATA_HOME이 설정되어 있으면 ${XDG_DATA_HOME}/.local/share/quarto/logs, 그렇지 않으면 ${HOME}/.local/share/quarto/logs

메모리 부족 문제

대규모 프로젝트나 웹사이트를 빌드할 때 메모리 제한에 걸릴 수 있습니다. 이 경우 QUARTO_DENO_V8_OPTIONS 환경 변수를 조정하는 것을 고려하세요.

아래 예시는 Deno가 사용할 최대 메모리를 8GB로 설정합니다. 컴퓨터 한도에 맞게 조정하세요.

PowerShell에서:

$env:QUARTO_DENO_V8_OPTIONS="--max-old-space-size=8192"

bash 계열 셸에서:

export QUARTO_DENO_V8_OPTIONS=--max-old-space-size=8192

설치 프로그램 문제

macOS에서 설치 프로그램은 /var/log/install.log에 출력을 기록합니다. 이 파일을 확인하면 무엇이 잘못되었는지 힌트를 얻을 수 있습니다.

Warning

공개 포럼에 도움을 요청하려는 경우 모든 macOS 설치 프로그램이 동일한 파일(/var/log/install.log)에 기록한다는 점을 유의하세요. 원치 않는 설치 정보가 노출되지 않도록 주의해야 합니다.

PDF/LaTeX 문제

quarto가 시스템에 설치된 texlive를 발견하면 그 버전을 사용합니다. PDF 렌더링에 문제가 있다면 texlive가 최신인지 확인하세요. 또는 quarto install tinytex를 호출해 quarto 자체 버전을 사용하도록 할 수도 있습니다.

환경, 라이브러리, 의존성

복잡한 문제의 일반적인 원인 중 하나는 한 시스템에 여러 R/Python 설치본이 있는 경우입니다. Quarto는 R 또는 Python 설치본을 찾으려 하지만, 셸 환경이 다른 설치본을 가리킬 때도 있습니다.

knitr

quarto가 잘못된 R 설치본을 찾고 있다고 의심된다면, 아래 .qmd 파일을 실행해 Quarto가 확인하는 R 설치 정보를 가져올 수 있습니다:

---
engine: knitr
---

```{r}
sessionInfo()
Sys.getenv()
.libPaths()

# If the sessioninfo package is available, 
# it provides output that is easier to read,
# and can write its results to a file
sessioninfo:::session_info(to_file = "quarto-session-info-output.txt")
```

그런 다음 R 환경에서 동일한 명령을 실행하고 출력 결과를 비교할 수 있습니다. sessioninfo를 사용할 수 있다면, 다음과 같이 출력 차이를 더 직접적으로 확인할 수 있습니다:

sessioninfo:::session_diff(new = "quarto-session-info-output.txt")

julia

jupyter와 julia 엔진 모두에서 Julia 실행 및 설치 문제의 잠재적 원인 중 하나는 캐시에 남아 있는 오래된 라이브러리 버전입니다. 이런 경우 quarto check의 Quarto cache location에 표시된 디렉터리 내용을 삭제하는 것을 고려하세요.

고급

Jupyter 엔진 문제 디버깅

Jupyter 디버깅을 활성화하려면 YAML 프론트매터에 다음을 추가합니다:

execute:
  debug: true

Quarto는 Jupyter 노트북 실행 로그를 로그 디렉터리의 jupyter-kernel.log에 생성합니다.

Jupyter 실행이 실패 대신 멈춰 있는 경우, Quarto 실행 전에 환경에 QUARTO_JUPYTER_FLUSH_LOGS=true를 설정하면 로그를 즉시 플러시할 수 있습니다.

Jupyter가 잘못된 IJulia 커널을 찾는 경우

Jupyter는 설치된 커널의 전역 목록을 유지하며, Quarto는 jupyter kernelspec list로 이를 검색합니다. Julia 설치를 업그레이드하면 경로가 바뀌고 Jupyter의 kernelspec 파일 목록이 오래될 수 있습니다. 이 경우 IJulia 커널을 명시적으로 재설치해야 합니다.

Lua 필터 디버깅

유용한 Lua 헬퍼 함수

Quarto에는 Lua 필터 디버깅에 사용할 수 있는 유용한 Lua 헬퍼 함수가 포함되어 있습니다. 이 함수들은 quarto 모듈에서 사용할 수 있으며, 다음과 같이 사용할 수 있습니다:

quarto.log.output(obj) -- prints a potentially complex object to the console

필터 추적

환경에 QUARTO_TRACE_FILTERS=<FILENAME>.json를 설정하면 Quarto가 실행하는 Lua 필터의 추적 로그를 생성해 디스크에 기록합니다. 이 파일은 렌더링된 파일과 같은 디렉터리에 저장됩니다. 이 추적을 시각화하기 위한 대화형 Quarto 문서도 제공되며, quarto-cli 저장소의 tools/trace-viewer/trace-viewer.qmd에서 찾을 수 있습니다. quarto preview trace-viewer.qmd를 실행하면 “Trace 1”과 “Trace 2”라는 두 개의 텍스트 필드가 표시됩니다. JSON 파일을 각 필드에 드래그 앤 드롭하면 추적이 표시됩니다. 두 개의 추적을 비교하려면 각각의 필드에 드래그 앤 드롭하세요.